# 流式输出视觉呈现规范

> 版本：v1.3  
> 更新日期：2026-01-18  
> 适用范围：联系人侧边栏、智能回复等所有 AI 流式输出场景  
> 关联规范：[瑞小美AI接入规范](./瑞小美AI接入规范.md)、[技术栈标准](./瑞小美系统技术栈标准与字符标准.md)

---

## 〇、与现有架构的关系

### 后端：基于 AIService.chat_stream()

本规范的 SSE 事件协议是对现有 `AIService.chat_stream()` 的**扩展**，需后端配合改造：

```python
# 现有实现（仅输出 AI 文本）
async for chunk in ai.chat_stream(messages, prompt_name="analysis"):
    yield chunk

# 扩展实现（支持本规范的事件协议）
async def enhanced_stream(messages, steps, prompt_name):
    # 1. 发送 start 事件
    yield sse_event("start", {"request_id": req_id})
    
    # 2. 执行准备步骤并发送 step 事件
    for i, step in enumerate(steps):
        yield sse_event("step", {"index": i, "status": "active", **step})
        await step.execute()
        yield sse_event("step", {"index": i, "status": "done", **step})
    
    # 3. 调用 AI 并发送 thinking 事件
    async for chunk in ai.chat_stream(messages, prompt_name=prompt_name):
        if is_thinking_content(chunk):
            yield sse_event("thinking", {"text": chunk})
        else:
            # 4. 解析结构化结果并发送 field 事件
            result = parse_ai_json_response(accumulated_text)
            yield sse_event("result_start", {"fields": FIELD_DEFINITIONS})
            for key, value in result.items():
                yield sse_event("field", {"key": key, "value": value})
    
    # 5. 发送 complete 事件
    yield sse_event("complete", {"tokens_used": response.total_tokens})
```

### 前端：扩展现有组件

| 现有组件 | 本规范组件 | 关系 |
|----------|-----------|------|
| `stream.js` | `useAIStream.ts` | 扩展，增加阶段状态管理 |
| `useTypewriter.js` | `TypewriterList.vue` | 复用，用于列表打字效果 |
| `AIStreamDisplay.vue` | `AIStreamContainer.vue` | 升级替换，支持三阶段 |

---

## 一、设计目标

1. **Agent 步骤感**：让用户清晰感知 AI 正在执行的每个步骤
2. **思考过程透明**：展示 AI 的推理过程，增强信任感
3. **渐进式呈现**：结果逐步填充，而非一次性展示
4. **类 Cursor 体验**：思考内容渐隐消失，聚焦最新进展

---

## 二、展示模式

根据 AI 功能的使用场景，分为两种展示模式：

### 2.1 独立页面模式（Full Page Mode）

适用于功能复杂、结果丰富的 AI 分析，如：消费意向预测、客户画像、项目推荐等。

**特点**：
- 占据整个页面/Tab 区域
- 完整展示三阶段（准备→思考→渲染）
- 支持多模块骨架屏渐进填充

### 2.2 内嵌卡片模式（Inline Card Mode）

适用于轻量级 AI 功能，嵌入在列表项、会话卡片等位置，如：AI 会话摘要、快速标签等。

#### 状态机

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│    IDLE     │ ───▶ │  LOADING    │ ───▶ │  COMPLETE   │
│  待触发状态  │      │   加载中     │      │   结果展示   │
└─────────────┘      └─────────────┘      └─────────────┘
```

#### 必须满足的行为规范

| 状态 | 必须呈现的元素 | 必须支持的交互 |
|------|---------------|---------------|
| **IDLE** | 可点击的触发入口（如按钮/链接） | 点击后进入 LOADING |
| **LOADING** | 加载指示器 + 提示文案 | 可选：支持取消 |
| **COMPLETE** | AI 生成的结果内容 | 必须：提供"重新生成"入口 |
| **ERROR** | 错误提示 | 必须：可点击重试 |

#### 视觉示意

**IDLE（待触发）**

```
┌────────────────────────────────────────────────────────┐
│  19:12 - 19:25  来自: 瑞小美轻医美—农农    10条对话     │
│                                                        │
│     ✨生成AI摘要   |   查看聊天详情 ›                   │
│                                                        │
└────────────────────────────────────────────────────────┘
```

**LOADING（加载中）**

```
┌────────────────────────────────────────────────────────┐
│  19:12 - 19:25  来自: 瑞小美轻医美—农农    10条对话     │
│                                                        │
│     ○ 正在生成摘要...                                  │
│                                                        │
└────────────────────────────────────────────────────────┘
```

**COMPLETE（结果展示）**

```
┌────────────────────────────────────────────────────────┐
│  19:12 - 19:25  来自: 瑞小美轻医美—农农    10条对话     │
│                                                        │
│  ┌──────────────────────────────────────────────────┐  │
│  │  📋 AI会话摘要                          [重新生成] │  │
│  │                                                  │  │
│  │  • 员工推送年底消费回馈现金券活动                  │  │
│  │  • 客户对活动内容表示疑惑                         │  │
│  │  • 客户连续追问未获及时回复                       │  │
│  │  • 客户因等待过久表达不满情绪                     │  │
│  │  • 邀约到店领券尚未得到响应                       │  │
│  └──────────────────────────────────────────────────┘  │
│                                                        │
│                          查看聊天详情 ›                 │
│                                                        │
└────────────────────────────────────────────────────────┘
```

#### 缓存规则

| 场景 | 行为 |
|------|------|
| 无缓存 | 显示 IDLE 状态，等待用户触发 |
| 有缓存 | **直接显示 COMPLETE 状态**，跳过 IDLE |
| 重新生成 | 从 COMPLETE 进入 LOADING，完成后更新结果 |

#### 与独立页面模式的区别

| 特性 | 独立页面模式 | 内嵌卡片模式 |
|------|-------------|-------------|
| 空间 | 整个页面/Tab | 嵌入在卡片/列表项内 |
| 准备阶段 | 展示步骤列表 | **省略** |
| 思考阶段 | 展示 `<thinking>` 内容 | **省略** |
| 渲染阶段 | 骨架屏渐进填充 | 直接展示完整结果 |
| 初始触发 | 自动开始 | **等待用户点击** |

---

## 三、三阶段状态机（独立页面模式）

> 以下内容适用于**独立页面模式**

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  PREPARING  │ ───▶ │  THINKING   │ ───▶ │  RENDERING  │ ───▶ COMPLETE
│   准备阶段   │      │   思考阶段   │      │   渲染阶段   │
└─────────────┘      └─────────────┘      └─────────────┘
      │                    │                    │
      ▼                    ▼                    ▼
  步骤逐个打勾        步骤完成+思考区域      骨架屏+渐进填充
```

### 3.1 阶段定义

| 阶段 | 常量 | 触发条件 | 结束条件 |
|------|------|----------|----------|
| **准备阶段** | `PREPARING` | 请求开始 | 所有步骤完成 |
| **思考阶段** | `THINKING` | 收到第一个 `thinking` 事件 | 收到 `result_start` 事件 |
| **渲染阶段** | `RENDERING` | 收到 `result_start` 事件 | 收到 `complete` 事件 |
| **完成状态** | `COMPLETE` | 收到 `complete` 事件 | - |
| **错误状态** | `ERROR` | 收到 `error` 事件 或 请求异常 | 用户重试 |

---

## 四、视觉规范（独立页面模式）

### 4.1 准备阶段（PREPARING）

```
┌────────────────────────────────────────┐
│  🔄 准备分析数据...                     │
│                                        │
│  ✅ 获取客户信息                        │  ← 已完成
│  ◐ 查询CRM数据                         │  ← 进行中
│  ○ 加载对话记录                        │  ← 待完成
│  ○ 启动AI分析                          │
│                                        │
└────────────────────────────────────────┘
```

**必须实现的行为**：

| 步骤状态 | 必须呈现的元素 |
|---------|---------------|
| 已完成 (done) | 勾号图标 + 完成态样式 |
| 进行中 (active) | 加载动画 + 高亮样式 |
| 待完成 (pending) | 空心/灰色图标 + 弱化样式 |

**步骤数据结构**：

```typescript
interface PrepareStep {
  key: string
  text: string
}
```

---

### 4.2 思考阶段（THINKING）

```
┌────────────────────────────────────────┐
│  🔄 准备分析数据...                     │
│                                        │
│  ✅ 获取客户信息                        │
│  ✅ 查询CRM数据                         │
│  ✅ 加载对话记录                        │
│  ◐ AI 思考中                           │  ← 保持转圈
│                                        │
│  ─────────────────────────────────────  │
│                                        │
│  ┌──────────────────────────────────┐  │
│  │                     ▲ 渐隐遮罩    │  │
│  │  ...析客户消费偏好，发现近3个月  │  │
│  │  主要消费集中在光电类项目...     │  │
│  │  检查到院记录，上次到店是12月    │  │
│  │  15日，做的是热玛吉面部...       │  │
│  │  结合咨询铺垫记录，客户对抗衰█   │  │  ← 闪烁光标
│  └──────────────────────────────────┘  │
│                                        │
│  💡 AI正在分析CRM数据和对话记录...      │
└────────────────────────────────────────┘
```

**必须实现的行为**：

| 行为 | 说明 |
|------|------|
| 步骤列表保留 | 前序步骤显示完成状态，最后一步保持"AI思考中" |
| 思考内容展示 | 使用淡色字体，区别于正式结果 |
| 自动滚动 | 新内容出现时自动滚动到底部 |
| 渐隐效果 | 顶部内容渐隐消失，仅保留最后几行 |
| 闪烁光标 | 末尾显示闪烁光标，表示内容仍在输出 |

**类 Cursor 效果的核心**：
- 固定高度容器，`overflow: hidden`
- 顶部渐变遮罩实现渐隐
- 只显示最后 N 行（建议 5-8 行）
- 内容自动滚动到底部

---

### 4.3 渲染阶段（RENDERING）

当收到 `result_start` 事件时，页面**平滑切换**到结果视图。

#### 骨架屏示意

```
┌────────────────────────────────────────┐
│  🛒 可能消费项目                        │  ← 标题立即显示
│  ┌───────┐ ┌───────┐ ┌───────┐        │
│  │░░░░░░░│ │░░░░░░░│ │░░░░░░░│        │  ← 标签骨架
│  └───────┘ └───────┘ └───────┘        │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  ✅ 触发因素                            │
│  ├── ░░░░░░░░░░░░░░░░░░░░░░░░         │  ← 列表骨架
│  ├── ░░░░░░░░░░░░░░░░░░               │
│  └── ░░░░░░░░░░░░░░░░░░░░░            │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  ⚠️ 阻碍因素                            │
│  ├── ░░░░░░░░░░░░░░░░░░░░░░           │
│  └── ░░░░░░░░░░░░░░░░░░░░░░░░░        │
└────────────────────────────────────────┘
```

**必须实现的行为**：

| 行为 | 说明 |
|------|------|
| 阶段切换 | 从思考阶段平滑过渡到渲染阶段，有淡入淡出动画 |
| 骨架屏先行 | 收到 `result_start` 时立即显示所有模块的骨架屏 |
| 模块标题可见 | 每个模块的标题和图标立即显示，内容区为骨架 |
| 渐进填充 | 收到 `field` 事件时，对应模块骨架被实际内容替换 |
| 内容动画 | 内容出现时有渐进动画（打字机效果 或 淡入效果） |

#### 字段定义结构

后端在 `result_start` 事件中声明字段顺序，前端据此渲染骨架：

```typescript
interface FieldDefinition {
  key: string
  title: string
  type: 'tags' | 'list' | 'text'
  icon?: string
}
```

#### 字段类型与填充方式

| 类型 | 说明 | 建议填充效果 |
|------|------|-------------|
| `tags` | 标签列表 | 标签逐个淡入 |
| `list` | 文本列表 | 逐行出现，可选打字机效果 |
| `text` | 普通文本 | 打字机效果或直接显示 |

---

## 五、SSE 事件协议

### 5.1 事件类型定义（推荐方案）

| 事件类型 | 说明 | 触发阶段转换 |
|----------|------|--------------|
| `start` | 流开始 | → PREPARING |
| `step` | 步骤状态更新 | - |
| `thinking` | AI 思考内容（流式） | → THINKING |
| `result_start` | 结果开始，声明字段结构 | → RENDERING |
| `field` | 字段值更新 | - |
| `complete` | 流结束 | → COMPLETE |
| `error` | 错误 | → ERROR |

### 5.2 事件数据格式

#### start

```json
{
  "event": "start",
  "data": {
    "request_id": "req_123456",
    "message": "开始分析"
  }
}
```

#### step

```json
{
  "event": "step",
  "data": {
    "index": 0,
    "key": "customer",
    "text": "获取客户信息",
    "status": "done"  // pending | active | done
  }
}
```

#### thinking

```json
{
  "event": "thinking",
  "data": {
    "text": "正在分析客户消费偏好，发现近3个月..."
  }
}
```

**注意**：`thinking` 事件会多次发送，每次携带一小段文本，前端累积拼接。

#### result_start

```json
{
  "event": "result_start",
  "data": {
    "fields": [
      { "key": "likely_items", "title": "可能消费项目", "type": "tags" },
      { "key": "trigger_factors", "title": "触发因素", "type": "list" },
      { "key": "blocking_factors", "title": "阻碍因素", "type": "list" },
      { "key": "suggestions", "title": "跟进建议", "type": "list" }
    ]
  }
}
```

#### field

```json
{
  "event": "field",
  "data": {
    "key": "likely_items",
    "value": ["光电类项目（创始人卡续费/使用）", "皮肤管理项目", "抗衰项目"]
  }
}
```

```json
{
  "event": "field", 
  "data": {
    "key": "trigger_factors",
    "value": [
      "客户已主动预约明天下午2点半到店",
      "客户互动意愿强烈（主动说'你也太容易放弃了吧'）",
      "高净值客户（累计消费13万+，客单价1.8万+）",
      "持有创始人卡项，有消费习惯和忠诚度"
    ]
  }
}
```

#### complete

```json
{
  "event": "complete",
  "data": {
    "request_id": "req_123456",
    "tokens_used": 1250,
    "duration_ms": 3500
  }
}
```

#### error

```json
{
  "event": "error",
  "data": {
    "code": "AI_TIMEOUT",
    "message": "AI 分析超时，请重试"
  }
}
```

### 5.3 完整事件流示例

```
event: start
data: {"request_id": "req_123", "message": "开始分析"}

event: step
data: {"index": 0, "key": "customer", "text": "获取客户信息", "status": "active"}

event: step
data: {"index": 0, "key": "customer", "text": "获取客户信息", "status": "done"}

event: step
data: {"index": 1, "key": "crm", "text": "查询CRM数据", "status": "active"}

event: step
data: {"index": 1, "key": "crm", "text": "查询CRM数据", "status": "done"}

event: step
data: {"index": 2, "key": "chat", "text": "加载对话记录", "status": "active"}

event: step
data: {"index": 2, "key": "chat", "text": "加载对话记录", "status": "done"}

event: step
data: {"index": 3, "key": "ai", "text": "AI 思考中", "status": "active"}

event: thinking
data: {"text": "正在分析客户消费偏好..."}

event: thinking
data: {"text": "发现近3个月主要消费集中在光电类项目..."}

event: thinking
data: {"text": "检查到院记录，上次到店是12月15日..."}

event: thinking
data: {"text": "结合咨询铺垫记录，客户对抗衰项目有明确兴趣..."}

event: result_start
data: {"fields": [{"key": "likely_items", "title": "可能消费项目", "type": "tags"}, ...]}

event: field
data: {"key": "likely_items", "value": ["光电类项目", "皮肤管理项目", "抗衰项目"]}

event: field
data: {"key": "trigger_factors", "value": ["客户已主动预约...", "客户互动意愿强烈...", ...]}

event: field
data: {"key": "blocking_factors", "value": ["创始人卡项可能已过期...", "无明确咨询铺垫项目...", ...]}

event: field
data: {"key": "suggestions", "value": ["建议确认创始人卡续期情况", "可推荐当季抗衰活动"]}

event: complete
data: {"request_id": "req_123", "tokens_used": 1250, "duration_ms": 3500}
```

---

## 六、前端组件架构

### 6.1 组件层次（建议）

```
<AIStreamContainer>              <!-- 流式输出容器 -->
  ├── <PrepareSteps />           <!-- 准备步骤组件 -->
  ├── <ThinkingArea />           <!-- 思考区域组件 -->
  └── <ResultRenderer />         <!-- 结果骨架/内容组件 -->
```

### 6.2 状态管理

推荐封装 `useAIStream` Composable，管理以下状态：

```typescript
// 核心类型定义
type Phase = 'idle' | 'preparing' | 'thinking' | 'rendering' | 'complete' | 'error'
type StepStatus = 'pending' | 'active' | 'done'

interface PrepareStep {
  key: string
  text: string
}

interface FieldDefinition {
  key: string
  title: string
  type: 'tags' | 'list' | 'text'
  icon?: string
}

// Composable 返回值
interface UseAIStreamReturn {
  phase: Ref<Phase>                          // 当前阶段
  isLoading: ComputedRef<boolean>            // 是否加载中
  prepareSteps: ComputedRef<StepWithStatus[]> // 步骤列表（含状态）
  thinkingText: Ref<string>                  // 思考内容
  resultFields: Ref<FieldDefinition[]>       // 结果字段定义
  resultData: Ref<Record<string, unknown>>   // 结果数据
  error: Ref<Error | null>                   // 错误信息
  start: (url: string, params?: Record<string, unknown>) => Promise<void>
}
```

### 6.3 SSE 事件与状态映射

| SSE 事件 | 状态变更 |
|----------|----------|
| `start` | `phase` → `preparing` |
| `step` | 更新对应步骤状态 |
| `thinking` | `phase` → `thinking`，追加 `thinkingText` |
| `result_start` | `phase` → `rendering`，设置 `resultFields` |
| `field` | 更新 `resultData[key]` |
| `complete` | `phase` → `complete` |
| `error` | `phase` → `error`，设置 `error` |

---

## 七、动画效果要求

> 具体动画参数由开发自行决定，以下为必须实现的效果：

### 独立页面模式

| 效果 | 要求 |
|------|------|
| 步骤完成 | 有明显的"打勾"反馈（如弹出、闪烁） |
| 思考滚动 | 新内容出现时自动滚动到底部，旧内容渐隐上移 |
| 阶段切换 | 有过渡动画，避免突兀跳转 |
| 骨架屏 | 有脉冲/闪烁效果表示加载中 |
| 内容填充 | 渐进式出现（打字机或淡入均可） |

### 内嵌卡片模式

| 效果 | 要求 |
|------|------|
| 加载状态 | 有旋转/跳动等动态指示器 |
| 结果展开 | 有展开动画，避免突然出现 |
| 列表项 | 建议逐条淡入，增强流式感 |

---

## 八、错误处理

### 8.1 错误类型

| 错误码 | 说明 | 用户提示 |
|--------|------|----------|
| `NETWORK_ERROR` | 网络异常 | "网络连接失败，请检查网络后重试" |
| `AI_TIMEOUT` | AI 响应超时 | "AI 分析超时，请稍后重试" |
| `AI_QUOTA_EXCEEDED` | API 配额不足 | "AI 服务暂时不可用，请联系管理员" |
| `DATA_NOT_FOUND` | 数据不存在 | "未找到客户数据，请确认客户信息" |
| `PARSE_ERROR` | 解析失败 | "数据解析失败，请重试" |

### 8.2 错误界面

```
┌────────────────────────────────────────┐
│                                        │
│            ⚠️                          │
│                                        │
│      AI 分析超时，请稍后重试            │
│                                        │
│         [ 🔄 重试 ]                     │
│                                        │
└────────────────────────────────────────┘
```

---

## 九、缓存与重新分析规范（强制）

> ⚠️ **强制要求**：所有 AI 分析功能必须支持缓存机制和重新分析能力

### 9.1 核心原则

| 原则 | 要求 |
|------|------|
| **优先缓存** | 如有有效缓存，**必须**首先加载缓存数据，跳过流式请求 |
| **重新分析** | 页面**必须**提供"重新分析"按钮，允许用户强制刷新 |
| **缓存标识** | 必须展示数据来源（缓存/实时），让用户知晓数据时效 |

### 9.2 缓存状态定义

在三阶段状态机基础上，新增 `CACHED` 状态：

```
┌─────────────┐
│   CACHED    │  ◀──── 有有效缓存时直接进入
│  缓存加载    │
└──────┬──────┘
       │ 用户点击"重新分析"
       ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  PREPARING  │ ───▶ │  THINKING   │ ───▶ │  RENDERING  │ ───▶ COMPLETE
└─────────────┘      └─────────────┘      └─────────────┘
```

### 9.3 界面规范

#### 缓存数据展示

```
┌────────────────────────────────────────┐
│  🛒 消费意向分析                         │
│                                        │
│  ┌──────────────────────────────────┐  │
│  │  💡 数据来源：缓存（2小时前分析）   │  │  ← 缓存标识
│  └──────────────────────────────────┘  │
│                                        │
│  📊 消费概率：75%（高意向）              │
│  🛍️ 可能项目：光电类、皮肤管理           │
│  ...（完整结果内容）...                  │
│                                        │
│  ─────────────────────────────────────  │
│                                        │
│         [ 🔄 重新分析 ]                  │  ← 必须有此按钮
│                                        │
└────────────────────────────────────────┘
```

**必须呈现的元素**：

| 元素 | 要求 |
|------|------|
| 缓存标识 | 弱化样式，显示缓存时间（如"2小时前分析"） |
| 重新分析按钮 | 明确可点击，点击后进入流式请求流程 |

### 9.4 前端实现要求

缓存相关数据结构：

```typescript
interface CachedResult {
  data: Record<string, unknown>
  cachedAt: string              // ISO 8601 时间戳
  validUntil: string            // 过期时间
}
```

**必须实现的逻辑**：
1. 页面加载时优先检查缓存
2. 有效缓存直接展示，跳过流式请求
3. 提供"重新分析"功能，触发 `force_refresh`

### 9.5 后端 API 要求

所有 AI 分析接口必须支持 `force_refresh` 参数：

```
GET /api/sidebar/purchase-intent?external_userid=xxx&force_refresh=true
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `force_refresh` | boolean | `true` 时跳过缓存，强制重新分析 |

**响应中包含缓存元信息**：

```json
{
  "code": 0,
  "data": {
    "probability": 0.75,
    "likely_items": ["光电类", "皮肤管理"],
    "...": "..."
  },
  "meta": {
    "from_cache": true,
    "cached_at": "2026-01-18T10:30:00+08:00",
    "valid_until": "2026-01-19T10:30:00+08:00"
  }
}
```

### 9.6 缓存有效期建议

| 分析类型 | 建议有效期 | 说明 |
|----------|-----------|------|
| 消费意向预测 | 24 小时 | 数据变化不频繁 |
| 客户画像 | 12 小时 | 对话可能更新 |
| 项目推荐 | 24 小时 | 依赖消费历史 |
| 接待策略 | 2 小时 | 到店场景需实时 |

---

## 十、AI 响应解析与容错

> 参考：[瑞小美AI接入规范](./瑞小美AI接入规范.md) - AI 响应解析规范章节

### 10.1 后端解析要求

AI 返回的 JSON 可能存在格式问题，后端**必须**使用公共解析函数：

```python
from shared_backend.services.ai_service import parse_ai_json_response, safe_parse_ai_json

# 在发送 field 事件前解析 AI 输出
try:
    result, thinking = parse_ai_json_response(ai_response.content)
    
    # 发送 thinking 事件（如有）
    if thinking:
        yield sse_event("thinking", {"text": thinking})
    
    # 发送 result_start 和 field 事件
    yield sse_event("result_start", {"fields": FIELD_DEFINITIONS})
    for key, value in result.items():
        yield sse_event("field", {"key": key, "value": value})
        
except json.JSONDecodeError as e:
    # 解析失败，发送错误事件
    yield sse_event("error", {
        "code": "PARSE_ERROR",
        "message": f"AI 输出解析失败: {str(e)}"
    })
```

### 10.2 推荐：使用 json-repair 库

对于 JSON 格式问题较多的场景，推荐使用 `json-repair` 库（GitHub 4000+ 星）：

```python
from json_repair import loads as json_repair_loads

# 自动修复常见 JSON 格式问题
result = json_repair_loads(ai_raw_output)
```

**能修复的问题**：
- 单引号 → 双引号
- 未闭合括号补齐
- `True/False/None` → `true/false/null`
- 尾部逗号移除
- Markdown 代码块提取

### 10.3 前端容错处理

前端收到 `field` 事件时，应做类型校验：

```typescript
function onField(data: { key: string; value: unknown }): void {
  const { key, value } = data
  
  // 类型校验
  const fieldDef = resultFields.value.find(f => f.key === key)
  if (!fieldDef) return
  
  // 根据类型校验 value
  if (fieldDef.type === 'tags' && !Array.isArray(value)) {
    console.warn(`字段 ${key} 期望数组，实际: ${typeof value}`)
    resultData.value[key] = []
    return
  }
  
  if (fieldDef.type === 'list' && !Array.isArray(value)) {
    console.warn(`字段 ${key} 期望数组，实际: ${typeof value}`)
    resultData.value[key] = []
    return
  }
  
  resultData.value[key] = value
}
```

---

## 十一、性能优化建议

1. **防抖思考文本更新**：每 50ms 批量更新一次 DOM，避免频繁重绘
2. **虚拟滚动**：思考区域内容过长时使用虚拟滚动
3. **骨架屏预渲染**：结果骨架使用 `v-show` 而非 `v-if`
4. **动画硬件加速**：使用 `transform` 和 `opacity`，避免触发重排

---

## 十二、兼容性说明

- **SSE 支持**：所有现代浏览器均支持 `fetch` + `ReadableStream`
- **CSS 动画**：使用标准 CSS3 动画，兼容 Chrome 60+, Safari 12+, Firefox 55+
- **字体回退**：等宽字体使用系统回退链
- **字符编码**：UTF-8（符合[技术栈标准](./瑞小美系统技术栈标准与字符标准.md#字符标准)）

```css
font-family: "SF Mono", "Monaco", "Inconsolata", "Fira Code", "Consolas", monospace;
```

---

## 十三、待确认事项

- [ ] 后端 SSE 事件协议改造排期
- [ ] 是否需要支持中断/取消流式请求
- [ ] 移动端适配细节（触摸滚动、字体大小）
- [x] ~~是否需要保存分析历史~~ → 已确认：必须支持缓存，详见第九章

---

*最后更新：2026-01-18*