# Ask Agent 模块 PRD（产品需求文档）

> 版本：v2.0 | 更新日期：2025-02-13 | 所属模块：百智个人知识库 2.0

---

## 一、模块概述

### 1.1 功能定位

Ask Agent 是百智个人知识库的智能问答核心模块，用户可通过自然语言对话方式向知识库提问。Agent 基于 RAG（检索增强生成）技术进行跨文件语义检索，结合联网搜索（WebSearch）与深度思考（Deep Thinking）能力，生成带引用溯源的结构化回答。支持多轮对话、长短期记忆、会话管理。

### 1.2 核心价值

| 价值维度 | 描述 |
|---------|------|
| 效率提升 | 用户无需逐个打开文件查找信息，通过自然语言即可快速获取答案 |
| 精准定位 | 基于语义检索而非关键词匹配，准确理解用户意图 |
| 可信溯源 | 每条回答标注引用来源（知识库/联网搜索），支持一键查看原文 |
| 知识增强 | 结合联网搜索，补充知识库外的实时信息 |
| 深度分析 | 深度思考能力对复杂问题进行多步推理和结构化分析 |

### 1.3 模块能力全景图

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Ask Agent 模块                              │
├──────────────┬──────────────────┬──────────────┬───────────────────┤
│  ① 需求输入   │   ② Agent 能力    │  ③ 内容输出   │  ④ 会话管理      │
├──────────────┼──────────────────┼──────────────┼───────────────────┤
│ ·对话框能力   │ ·内容检索         │ ·前置检索状态 │ ·新建会话         │
│ ·交互规则     │   - 知识库 RAG    │ ·深度思考过程 │   (新建 Thread)   │
│ ·业务逻辑     │   - WebSearch    │ ·正文内容     │ ·历史会话         │
│ ·附件/文件    │ ·记忆系统         │ ·引用标注     │   (Thread 列表)   │
│ ·快捷提问     │   - 短期记忆      │ ·溯源浮层     │ ·会话切换/删除    │
│              │   - 长期记忆      │ ·操作按钮     │                   │
│              │ ·深度思考         │   - 复制      │                   │
│              │ ·工具调用         │   - 评价      │                   │
└──────────────┴──────────────────┴──────────────┴───────────────────┘
```

---

## 二、需求输入阶段

### 2.1 对话框能力

#### 2.1.1 输入区结构

```
┌─ Agent 输入区 ─────────────────────────────────────┐
│                                                     │
│ ┌─ 附件区（有附件时显示）────────────────────────┐  │
│ │ [📄 文件A.pdf ✕] [📄 文件B.docx ✕]            │  │
│ └───────────────────────────────────────────────┘  │
│                                                     │
│ ┌─ 输入框 ──────────────────────────────────────┐  │
│ │ [📎]                                          │  │
│ │                                               │  │
│ │  输入你的问题...                               │  │
│ │                                               │  │
│ │                                    [发送 ➤]   │  │
│ └───────────────────────────────────────────────┘  │
│                                                     │
│ Enter 发送 · Shift+Enter 换行                       │
└─────────────────────────────────────────────────────┘
```

#### 2.1.2 对话框能力矩阵

| 能力 | 描述 | 交互方式 | 限制 |
|------|------|---------|------|
| 文本输入 | 支持多行自然语言输入 | 直接在 textarea 中输入 | 单条消息最大 2000 字符 |
| 附加文件 | 指定 Agent 针对特定文件回答 | 点击 📎 按钮选择文件 | 单次最多附加 5 个文件 |
| 快捷提问 | 预设常用问题模板，一键发送 | 点击欢迎页的快捷按钮 | 仅在空会话时展示 |
| 上下文关联 | 自动携带当前 Thread 历史上下文 | 自动（无需用户操作） | 最近 10 轮对话 |

#### 2.1.3 附件能力详细设计

**附件来源：**

| 来源 | 入口 | 说明 |
|------|------|------|
| 知识库文件 | 📎 → 知识库选择器 | 从已有知识库文件中选择 |
| 本地文件 | 📎 → 本地上传 | 上传本地文件作为临时附件 |
| 拖拽文件 | 从文件列表拖入输入区 | 快捷附加方式 |

**附件展示：**

```
┌─ 附件 Chip ──────────┐
│ 📄 文件名.pdf    [✕] │  ← 紫色背景，点击 ✕ 移除
└──────────────────────┘
```

**附件业务逻辑：**

| # | 规则 |
|---|------|
| 1 | 附加文件后，Agent 优先在指定文件中检索（缩小检索范围） |
| 2 | 同名文件不可重复添加，Toast 提示"该文件已添加" |
| 3 | 消息发送后附件区清空，附件信息随消息一起存入 Run |
| 4 | 临时上传的本地文件在会话结束后自动清理 |

### 2.2 交互规则

| # | 交互行为 | 规则描述 |
|---|---------|---------|
| 1 | 输入框聚焦 | 边框变为主题色（#6C5CE7），出现 3px 外发光效果 |
| 2 | 输入框自适应 | 随内容自动扩展高度，最小 56px，最大 120px |
| 3 | 发送按钮状态 | 输入框为空时置灰禁用（background: var(--border)），有内容时激活 |
| 4 | 发送消息 | 点击发送按钮或按 Enter 键发送 |
| 5 | 换行输入 | Shift + Enter 换行，不触发发送 |
| 6 | 附件添加 | 点击 📎 按钮，弹出文件选择（本地/知识库） |
| 7 | 附件展示 | 已添加文件以 Chip 标签形式显示在输入框上方 |
| 8 | 附件移除 | 点击 Chip 上的 ✕ 移除附件，hover 时 ✕ 变红 |
| 9 | 发送后清空 | 消息发送后清空输入框文本和附件区 |
| 10 | 流式输出中 | AI 回答生成过程中，发送按钮禁用，防止重复发送 |
| 11 | 空内容拦截 | 无文本且无附件时，发送按钮不可点击 |

### 2.3 业务逻辑

```
用户输入/附加文件
        │
        ▼
┌───────────────────┐
│  输入校验          │  ← 非空校验、字符数限制
└───────┬───────────┘
        │
        ▼
┌───────────────────┐
│  消息构建          │  ← content + attachments + timestamp
└───────┬───────────┘
        │
        ▼
┌───────────────────┐
│  生成 run_id       │  ← 本轮对话唯一标识
└───────┬───────────┘
        │
        ▼
┌───────────────────┐
│  UI 即时反馈       │  ← 用户消息立即上屏（右对齐）
│                   │     清空输入框和附件区
│                   │     发送按钮禁用
└───────┬───────────┘
        │
        ▼
┌───────────────────┐
│  触发 Agent 响应   │  ← 进入内容输出阶段
└───────────────────┘
```

### 2.4 快捷提问入口

**展示条件：** 仅在空会话（欢迎页）时展示

**快捷按钮：**

| 按钮 | 预设问题 | 图标 |
|------|---------|------|
| 总结文件 | "总结最近上传的文件内容" | 📝 |
| 搜索知识库 | "搜索知识库中关于销售策略的内容" | 🔍 |
| 分析要点 | "分析百融云创AI智能体系的核心要点" | 💡 |
| 整理纪要 | "将会议记录整理成结构化笔记" | 📋 |

**交互：** 点击后自动填入输入框并立即发送

---

## 三、Agent 能力

### 3.1 能力架构总览

```
┌─────────────────────────────────────────────────────────────────┐
│                        Agent 能力层                              │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                     意图识别 & 路由                       │   │
│  │  用户提问 → 意图分类 → 能力路由 → 执行策略               │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐    │
│  │  内容检索    │  │   记忆系统   │  │   深度思考 & 推理    │    │
│  ├─────────────┤  ├─────────────┤  ├─────────────────────┤    │
│  │ 知识库 RAG  │  │ 短期记忆     │  │ 多步推理            │    │
│  │ WebSearch   │  │  Thread历史  │  │ 结构化分析          │    │
│  │ 文件定向检索 │  │  (多轮对话)  │  │ 对比/归纳/演绎      │    │
│  └─────────────┘  │  单轮=RunID  │  │ 思考过程可视化      │    │
│                   ├─────────────┤  └─────────────────────┘    │
│                   │ 长期记忆     │                              │
│                   │  用户画像    │                              │
│                   │  用户偏好    │                              │
│                   │  知识记忆    │                              │
│                   └─────────────┘                              │
└─────────────────────────────────────────────────────────────────┘
```

### 3.2 内容检索

#### 3.2.1 知识库 RAG 检索

**检索流程：**

```
用户提问（+ 附件上下文）
         │
         ▼
┌──────────────────┐
│  Query 预处理     │
│  ·意图识别        │  ← 判断是否需要知识库检索
│  ·关键词提取      │  ← 提取核心检索词
│  ·Query 改写      │  ← 优化检索语句（多轮对话时结合历史）
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  检索范围确定      │
│  ·有附件 → 指定文件范围检索  │
│  ·无附件 → 全知识库检索      │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  向量化 Embedding │  ← 将 Query 转为高维向量
└────────┬─────────┘
         │
         ▼
┌──────────────────┐     ┌────────────────────────┐
│  向量检索         │ ──→ │  知识库向量索引          │
│  (ANN Search)    │     │  ·文档切片向量化         │
│                  │     │  ·元数据索引（文件名、   │
│                  │     │   类型、时间等）         │
└────────┬─────────┘     └────────────────────────┘
         │
         ▼
┌──────────────────┐
│  Rerank 精排      │  ← 语义相关性重排序
│  ·Cross-Encoder  │
│  ·筛选 Top-N     │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  结果输出         │  ← 返回 Top-N 片段 + 元数据（文件名、位置）
└──────────────────┘
```

**检索参数：**

| 参数 | 值 | 说明 |
|------|-----|------|
| Chunk Size | 512 tokens | 文档切片大小 |
| Chunk Overlap | 64 tokens | 切片重叠区域，保证语义连续性 |
| Top-K | 5 | 初次向量检索召回数量 |
| Rerank Top-N | 3 | 精排后保留数量（最终注入 Prompt） |
| Similarity Threshold | 0.7 | 相似度阈值，低于此值判定为无相关内容 |

**检索结果数据结构：**

```json
{
  "results": [
    {
      "chunk_id": "string",
      "file_id": "string",
      "file_name": "string",
      "content": "string (原文片段)",
      "score": "number (0-1)",
      "metadata": {
        "source": "知识库",
        "page": "number | null",
        "position": "string (段落定位)"
      }
    }
  ]
}
```

#### 3.2.2 WebSearch 联网搜索

**触发条件：**

| 条件 | 判断方式 | 说明 |
|------|---------|------|
| 知识库无相关内容 | RAG 检索 Top-1 score < 0.7 | 知识库中找不到相关信息 |
| 用户明确要求 | 意图识别命中"搜索"类意图 | 问题含"最新"、"搜索"、"网上"等关键词 |
| 时效性问题 | 意图识别命中"时效"类意图 | 涉及近期事件、实时数据、新闻 |
| 知识库+联网混合 | 复杂问题需要外部补充 | 知识库有部分信息但不完整 |

**搜索流程：**

```
触发联网搜索
      │
      ▼
┌─────────────────┐
│  Query 优化      │  ← 从对话上下文提取搜索关键词
│                 │     去除口语化表达，优化为搜索语句
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  Web Search API │  ← 调用搜索引擎 API（Google/Bing）
│                 │     返回 Top-10 搜索结果
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  结果过滤 & 提取  │
│  ·去重           │
│  ·相关性过滤     │
│  ·可信度评估     │  ← 优先权威来源（.gov/.edu/知名媒体）
│  ·内容提取       │  ← 提取网页核心段落
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  融合排序        │  ← 与 RAG 结果合并
│                 │     统一 Rerank 排序
│                 │     标注来源类型（知识库/联网搜索）
└─────────────────┘
```

**搜索结果数据结构：**

```json
{
  "results": [
    {
      "title": "string (网页标题)",
      "url": "string (网页URL)",
      "snippet": "string (摘要片段)",
      "content": "string (提取的核心内容)",
      "source": "联网搜索",
      "credibility": "high | medium | low"
    }
  ]
}
```

### 3.3 记忆系统

#### 3.3.1 记忆架构

```
┌─────────────────────────────────────────────────────────┐
│                      Agent 记忆系统                      │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │              短期记忆 (Working Memory)            │   │
│  │                                                   │   │
│  │  Thread 历史（含多轮对话）                         │   │
│  │  ┌─────────────────────────────────────────┐     │   │
│  │  │  Thread_A (thread_id: xxx)               │     │   │
│  │  │  ├─ Run 1 (run_id: r001)                │     │   │
│  │  │  │  ├─ User: "Q3营收增长原因？"          │     │   │
│  │  │  │  └─ Agent: "根据知识库数据..."        │     │   │
│  │  │  ├─ Run 2 (run_id: r002)                │     │   │
│  │  │  │  ├─ User: "具体哪些行业贡献最大？"    │     │   │
│  │  │  │  └─ Agent: "金融行业占比最高..."      │     │   │
│  │  │  └─ Run N ...                           │     │   │
│  │  └─────────────────────────────────────────┘     │   │
│  │                                                   │   │
│  │  ·新建会话 = 新建 Thread_id                       │   │
│  │  ·单轮对话 = 一个 Run_id                          │   │
│  │  ·上下文窗口：最近 10 轮（约 8K tokens）           │   │
│  │  ·超出窗口 → 自动摘要压缩                         │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │              长期记忆 (Long-term Memory)          │   │
│  │                                                   │   │
│  │  ┌─ 用户画像 ────────────────────────────────┐   │   │
│  │  │  ·职业角色（销售/产品/研发/管理等）         │   │   │
│  │  │  ·身份标签（部门、职级、行业）             │   │   │
│  │  │  ·专业领域（金融风控/AI产品/市场营销等）   │   │   │
│  │  └────────────────────────────────────────────┘   │   │
│  │                                                   │   │
│  │  ┌─ 用户偏好 ────────────────────────────────┐   │   │
│  │  │  行为偏好：                                │   │   │
│  │  │  ·回答长度偏好（简洁/适中/详细）           │   │   │
│  │  │  ·回答风格偏好（专业/通俗/结构化）         │   │   │
│  │  │  内容偏好：                                │   │   │
│  │  │  ·关注主题领域                             │   │   │
│  │  │  ·高频访问文件                             │   │   │
│  │  │  反馈偏好：                                │   │   │
│  │  │  ·历史评分分布                             │   │   │
│  │  │  ·反馈中的高频关键词                       │   │   │
│  │  └────────────────────────────────────────────┘   │   │
│  │                                                   │   │
│  │  ┌─ 知识记忆 ────────────────────────────────┐   │   │
│  │  │  ·知识库文件（持久化，用户上传/导入的文件） │   │   │
│  │  │  ·外部信息源（当前内容生成依赖的联网搜索   │   │   │
│  │  │   结果，会话级缓存）                       │   │   │
│  │  │  ·上传附件（对话中临时上传的本地文件，     │   │   │
│  │  │   会话级缓存，会话结束后清理）             │   │   │
│  │  └────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

### 3.5 深度思考（Deep Thinking）

#### 3.5.1 功能定位

深度思考是 Agent 面对复杂问题时的高阶推理能力。当问题需要多步推理、跨文件对比分析、数据归纳演绎时，Agent 自动启用深度思考模式，并将思考过程可视化展示给用户。

#### 3.5.2 触发条件

| 条件 | 示例 | 说明 |
|------|------|------|
| 多文件对比 | "对比Q2和Q3的营收变化原因" | 需要跨文件提取并对比数据 |
| 因果分析 | "分析客户流失率上升的根本原因" | 需要多步因果推理 |
| 综合归纳 | "总结今年所有会议的核心决策" | 需要跨多份文件归纳 |
| 趋势预测 | "基于历史数据预测下季度趋势" | 需要数据分析和推理 |
| 方案建议 | "针对当前问题给出解决方案" | 需要综合分析后给出建议 |

#### 3.5.3 思考过程可视化

```
┌─ 深度思考过程（可折叠）──────────────────────┐
│                                              │
│  💭 思考中...                                │
│                                              │
│  1. 分析问题：用户询问Q3营收增长原因，需要    │
│     从多份报告中提取营收数据和业务变化...      │
│                                              │
│  2. 检索相关文件：找到3份相关报告，包含       │
│     Q3财务数据、客户拓展记录、产品迭代日志... │
│                                              │
│  3. 数据对比：Q2营收2.1亿 vs Q3营收2.8亿，   │
│     增长33%，主要增量来自...                  │
│                                              │
│  4. 归因分析：增长驱动因素包括三个维度...     │
│                                              │
│  [▼ 收起思考过程]                             │
└──────────────────────────────────────────────┘
```

#### 3.5.4 深度思考交互规则

| # | 规则 |
|---|------|
| 1 | 思考过程以折叠卡片形式展示在正文上方 |
| 2 | 默认展开显示，用户可点击收起 |
| 3 | 思考过程为流式输出，逐步展示推理步骤 |
| 4 | 思考完成后自动开始输出正文回答 |
| 5 | 思考过程使用灰色背景区分于正文内容 |
| 6 | 简单问题不触发深度思考，直接输出回答 |

#### 3.5.5 深度思考与普通回答的区别

| 维度 | 普通回答 | 深度思考回答 |
|------|---------|-------------|
| 触发条件 | 简单事实性问题 | 复杂分析/对比/推理问题 |
| 响应结构 | 检索状态 → 正文 → 引用 | 检索状态 → 思考过程 → 正文 → 引用 |
| 推理深度 | 单步检索+生成 | 多步推理+交叉验证 |
| 耗时 | 3-8秒 | 8-20秒 |
| 输出质量 | 信息检索型回答 | 分析洞察型回答 |

---

## 四、内容输出阶段

### 4.1 输出流程总览

```
Agent 响应触发
      │
      ▼
┌─────────────────────────────────────────────────┐
│  ① 前置检索状态展示                              │
│                                                 │
│  [✓] 正在检索知识库...  → 找到 3 个相关片段      │
│  [✓] 正在联网搜索...    → 获取 2 条结果          │
│  [○] 深度思考分析中...                           │
└───────────────────────┬─────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│  ② 深度思考过程（复杂问题时展示，可折叠）         │
│                                                 │
│  💭 思考中...                                   │
│  1. 分析问题维度...                              │
│  2. 交叉检索验证...                              │
│  3. 归纳核心结论...                              │
└───────────────────────┬─────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│  ③ 正文内容（流式输出）                          │
│                                                 │
│  根据知识库中的数据，Q3季度营收达到2.8亿元，     │
│  同比增长23.5%[1]。主要增长驱动因素包括：        │
│                                                 │
│  1. 新客户拓展：新增合作客户47家[2]              │
│  2. 产品升级：智能风控引擎v3.0上线               │
│  3. 行业深耕：三大行业收入占比提升至78%[3]       │
│  █ (光标闪烁)                                   │
└───────────────────────┬─────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│  ④ 引用来源卡片                                  │
│                                                 │
│  📎 引用来源                                    │
│  ┌──────────────────────────────────────────┐   │
│  │ [1] 📄 Q3季度营收分析报告.docx  · 知识库  │   │
│  │ [2] 📄 2025年度工作总结.docx    · 知识库  │   │
│  │ [3] 🌐 2026企业AI销售趋势      · 联网搜索 │   │
│  └──────────────────────────────────────────┘   │
└───────────────────────┬─────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│  ⑤ 操作按钮                                     │
│                                                 │
│  [📋 复制]  [⭐ 评价]                           │
└─────────────────────────────────────────────────┘
```

### 4.2 前置检索状态（Search Steps）

#### 4.2.1 状态展示

```
┌─ 检索状态卡片 ────────────────────────────────┐
│                                               │
│  [✓] 正在检索知识库...  → 找到 3 个相关片段    │
│  [✓] 正在联网搜索...    → 获取 2 条结果        │
│  [○] 深度思考分析中...                         │
│                                               │
└───────────────────────────────────────────────┘
```

#### 4.2.2 状态流转

| 步骤 | 初始状态 | 进行中状态 | 完成状态 |
|------|---------|-----------|---------|
| 知识库检索 | - | ○ 正在检索知识库... (spinner) | ✓ 找到 N 个相关片段 |
| 联网搜索 | - | ○ 正在联网搜索... (spinner) | ✓ 获取 N 条结果 |
| 深度思考 | - | ○ 深度思考分析中... (spinner) | ✓ 分析完成 |

#### 4.2.3 状态展示规则

| # | 规则 |
|---|------|
| 1 | 检索状态以卡片形式展示在回答正文上方 |
| 2 | 每个步骤依次执行，进行中显示 spinner 动画 |
| 3 | 步骤完成后图标变为 ✓（绿色），显示结果摘要 |
| 4 | 联网搜索仅在触发条件满足时展示 |
| 5 | 深度思考仅在复杂问题时展示 |
| 6 | 全部步骤完成后开始流式输出正文 |

### 4.3 正文内容

#### 4.3.1 内容格式支持

| 格式 | 支持 | 说明 |
|------|------|------|
| Markdown | ✓ | 标题、列表、加粗、斜体、分割线 |
| 代码块 | ✓ | 支持语法高亮 |
| 表格 | ✓ | 简单表格渲染 |
| 引用标注 | ✓ | 行内 [1][2][3] 形式标注 |
| 数学公式 | ✓ | LaTeX 基础公式 |

#### 4.3.2 流式输出规则

| # | 规则 |
|---|------|
| 1 | 逐字符输出，模拟打字机效果 |
| 2 | 输出速度：约 30-50 字符/秒 |
| 3 | 输出过程中显示闪烁光标（█） |
| 4 | 对话区自动滚动到底部跟随输出 |
| 5 | 输出完成后光标消失，显示引用来源和操作按钮 |
| 6 | 输出过程中发送按钮禁用 |

### 4.4 引用标注与溯源

#### 4.4.1 行内引用标注

正文中以 `[1]` `[2]` `[3]` 形式标注引用来源，点击数字可查看引用详情。

**标注样式：**

| 属性 | 值 |
|------|-----|
| 尺寸 | 15px × 15px |
| 背景 | 主题色浅色（#F0EDFF） |
| 文字 | 主题色（#6C5CE7），9px，加粗 |
| 位置 | 上标形式（vertical-align: super） |
| 交互 | hover 时背景变为主题色，文字变白 |
| 点击 | 弹出溯源浮层 |

#### 4.4.2 引用来源卡片

```
┌─ 来源卡片 ─────────────────────────────────────┐
│                                                │
│  [1]  📄 Q3季度营收分析报告.docx  · 知识库      │
│  [2]  📄 2025年度工作总结.docx    · 知识库      │
│  [3]  🌐 2026企业AI销售趋势      · 联网搜索     │
│                                                │
└────────────────────────────────────────────────┘
```

**卡片交互：** 点击卡片弹出溯源浮层，hover 时边框变主题色

#### 4.4.3 溯源浮层（Citation Popover）

点击引用标注或来源卡片，弹出溯源浮层：

**知识库来源浮层：**

```
┌─ 引用溯源 ──────────────────────── ✕ ─┐
│                                       │
│  [1]  Q3季度营收分析报告.docx         │
│       [📚 知识库]  ← 紫色标签         │
│                                       │
│  ─────────────────────────────────    │
│                                       │
│  📝 引用原文                          │
│  ┌─────────────────────────────────┐ │
│  │ "Q3季度总营收达到2.8亿元，同比   │ │
│  │  增长23.5%。主要增长来自金融行   │ │
│  │  业客户的深度合作，单客户平均    │ │
│  │  收入提升18%..."                │ │
│  └─────────────────────────────────┘ │
│  ← 左侧紫色边框                      │
│                                       │
└───────────────────────────────────────┘
```

**联网搜索来源浮层：**

```
┌─ 引用溯源 ──────────────────────── ✕ ─┐
│                                       │
│  [3]  2026企业AI销售趋势              │
│       [🌐 联网搜索]  ← 蓝色标签       │
│                                       │
│  ─────────────────────────────────    │
│                                       │
│  📝 引用原文                          │
│  ┌─────────────────────────────────┐ │
│  │ "据Gartner 2026年报告，企业级   │ │
│  │  AI销售工具市场规模预计达到180  │ │
│  │  亿美元，同比增长34%..."        │ │
│  └─────────────────────────────────┘ │
│  ← 左侧蓝色边框                      │
│                                       │
└───────────────────────────────────────┘
```

**来源类型视觉区分：**

| 来源类型 | 图标 | 标签色 | 引用边框色 | 背景色 |
|---------|------|--------|-----------|--------|
| 知识库 | 📚 书本 SVG | #6C5CE7（紫） | #A29BFE | #F0EDFF |
| 联网搜索 | 🌐 地球 SVG | #0369A1（蓝） | #0369A1 | #F0F9FF |

**溯源浮层交互规则：**

| # | 规则 |
|---|------|
| 1 | 浮层定位在点击元素附近，自动避免超出视口 |
| 2 | 浮层最大宽度 320px，最大高度 280px |
| 3 | 点击 ✕ 或遮罩层关闭浮层 |
| 4 | 引用原文超长时浮层内部可滚动 |
| 5 | 知识库来源可点击文件名跳转到文件预览 |

### 4.5 操作按钮

#### 4.5.1 按钮列表

| 按钮 | 图标 | 样式 | 功能 | 交互反馈 |
|------|------|------|------|---------|
| 复制 | 📋 线框 SVG | 线框按钮 | 复制回答正文到剪贴板 | Toast "已复制" |
| 评价 | ⭐ 星星 SVG + "评价"文字 | 线框按钮 | 打开评价浮层 | 弹出评价弹窗 |

#### 4.5.2 按钮样式

| 属性 | 值 |
|------|-----|
| 边框 | 1px solid var(--border) |
| 背景 | white |
| 圆角 | 6px |
| 内边距 | 4px 8px |
| 字号 | 11px |
| 图标尺寸 | 14px × 14px |
| hover | 背景变灰，边框变主题色 |

### 4.6 评价功能

#### 4.6.1 评价浮层结构

```
┌─ ⭐ 评价回答质量 ──────────────── ✕ ─┐
│                                      │
│  请为本次回答打分（1-10分）           │
│                                      │
│  [1] [2] [3] [4] [5]                │
│  [6] [7] [8] [9] [10]               │
│                                      │
│  改进建议（可选）                     │
│  ┌────────────────────────────────┐  │
│  │                                │  │
│  │  请输入您的建议，帮助我们改进...│  │
│  │                                │  │
│  └────────────────────────────────┘  │
│                                      │
│                   [取消]  [提交评价]  │
└──────────────────────────────────────┘
```

#### 4.6.2 评价交互规则

| # | 交互行为 | 规则描述 |
|---|---------|---------|
| 1 | 打开评价 | 点击"评价"按钮，弹出评价浮层（居中遮罩） |
| 2 | 选择评分 | 点击 1-10 数字按钮，选中态：主题色背景+白色文字 |
| 3 | 输入建议 | 在文本框中输入改进建议（可选，非必填） |
| 4 | 提交校验 | 未选评分时 Toast "请先选择评分" |
| 5 | 提交成功 | 关闭浮层，Toast "感谢您的评价！评分：N分" |
| 6 | 关闭浮层 | 点击取消/✕/遮罩层关闭，不保存 |
| 7 | 重复评价 | 同一条回答可重复评价，以最新评价为准 |

#### 4.6.3 评价数据结构

```json
{
  "rating_id": "string (UUID)",
  "thread_id": "string",
  "run_id": "string",
  "score": "number (1-10)",
  "suggestion": "string | null",
  "created_at": "datetime"
}
```

#### 4.6.4 评分等级说明

| 分数区间 | 等级 | 说明 |
|---------|------|------|
| 9-10 | 优秀 | 回答准确、完整、有深度 |
| 7-8 | 良好 | 回答基本满足需求 |
| 5-6 | 一般 | 回答部分有用，有改进空间 |
| 3-4 | 较差 | 回答不够准确或完整 |
| 1-2 | 很差 | 回答无法满足需求 |

---

## 五、会话管理

### 5.1 会话数据模型

```
┌─────────────────────────────────────────────────────┐
│                    Thread（会话）                    │
├─────────────────────────────────────────────────────┤
│  thread_id: UUID                                    │
│  title: string (首条消息摘要，最长20字)              │
│  created_at: datetime                               │
│  updated_at: datetime                               │
│  message_count: number                              │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │  Run 1 (run_id: UUID)                       │   │
│  │  ├─ User Message                            │   │
│  │  └─ Assistant Message + Sources             │   │
│  ├─────────────────────────────────────────────┤   │
│  │  Run 2 (run_id: UUID)                       │   │
│  │  ├─ User Message                            │   │
│  │  └─ Assistant Message + Sources             │   │
│  ├─────────────────────────────────────────────┤   │
│  │  Run N ...                                  │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
```

**核心概念：**

| 概念 | 说明 |
|------|------|
| Thread | 一次完整的对话会话，包含多轮问答 |
| Run | 一轮问答（用户消息 + Agent 回答），由 run_id 唯一标识 |
| 新建会话 | 创建新 Thread，等于新建 thread_id |
| 多轮对话 | 同一 Thread 内的多个 Run |

### 5.2 新建会话

**触发方式：**

| 入口 | 位置 | 说明 |
|------|------|------|
| 新建按钮 | Agent 面板顶部工具栏 | 点击"+"图标 |

**新建流程：**

```
点击新建会话
      │
      ▼
┌─────────────────┐
│  保存当前会话    │  ← 如有未保存内容
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  生成新 thread_id │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  清空当前对话区   │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  显示欢迎页       │
│  （快捷提问入口） │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  Toast: 已开始新对话 │
└─────────────────┘
```

**交互规则：**

| # | 规则 |
|---|------|
| 1 | 新建会话不会删除历史会话，历史会话保留在列表中 |
| 2 | 当前会话有内容时，新建会话前自动保存当前会话 |
| 3 | 新会话的 title 在首次用户发送消息后自动生成 |
| 4 | title 取首条消息的前 20 个字符 + "..." |

### 5.3 历史会话（Thread 列表）

#### 5.3.1 历史面板结构

```
┌─ 历史会话 ──────────────────────── ✕ ─┐
│                                       │
│  🔍 搜索会话...                        │
│                                       │
│  ── 今天 ──                            │
│  ┌─────────────────────────────────┐  │
│  │  Q3季度营收分析讨论               │  │
│  │  2025-02-13 14:30 · 8条消息      │  │
│  └─────────────────────────────────┘  │
│                                       │
│  ── 昨天 ──                            │
│  ┌─────────────────────────────────┐  │
│  │  产品路线图规划                   │  │
│  │  2025-02-12 10:20 · 5条消息      │  │
│  └─────────────────────────────────┘  │
│                                       │
│  ── 更早 ──                            │
│  ┌─────────────────────────────────┐  │
│  │  竞品分析报告整理                 │  │
│  │  2025-02-11 16:45 · 12条消息     │  │
│  └─────────────────────────────────┘  │
│  ┌─────────────────────────────────┐  │
│  │  销售策略研讨                     │  │
│  │  2025-02-10 09:15 · 6条消息      │  │
│  └─────────────────────────────────┘  │
│                                       │
└───────────────────────────────────────┘
```

#### 5.3.2 历史会话交互规则

| # | 交互行为 | 规则描述 |
|---|---------|---------|
| 1 | 打开历史 | 点击 Agent 面板顶部"历史"图标（📜） |
| 2 | 搜索会话 | 在搜索框输入关键词，实时过滤会话标题 |
| 3 | 时间分组 | 按"今天"、"昨天"、"更早"分组展示 |
| 4 | 选择会话 | 点击会话项，加载该 Thread 的对话记录 |
| 5 | 删除会话 | hover 时显示删除图标，点击后二次确认 |
| 6 | 关闭面板 | 点击 ✕ 或遮罩层关闭历史面板 |
| 7 | 会话排序 | 按 updated_at 倒序排列，最新在前 |
| 8 | 当前会话 | 当前活跃的 Thread 在列表中高亮标记 |

#### 5.3.3 会话加载流程

```
点击历史会话项
      │
      ▼
┌─────────────────┐
│  保存当前会话    │  ← 如有未保存内容
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  切换 thread_id  │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  请求 Thread 数据 │  ← 加载该 Thread 的所有 Run
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  渲染历史消息    │  ← 按 Run 顺序渲染用户消息和 Agent 回答
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  关闭历史面板    │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  滚动到最新消息  │
└─────────────────┘
```

#### 5.3.4 会话数据保留策略

| 策略 | 规则 |
|------|------|
| 保留时长 | 默认保留 90 天 |
| 存储上限 | 单用户最多 200 个 Thread |
| 超限处理 | 自动归档最早的 Thread |
| 手动删除 | 用户可随时删除任意 Thread |

---

## 六、Agent 面板布局

### 6.1 整体结构

```
┌─ Agent 面板 (420px, 可拖拽调整宽度) ─────────────┐
│                                                  │
│ ┌─ 顶部栏 ────────────────────────────────────┐ │
│ │ [🤖] 百智 Agent        [+新建] [📜历史] [−] │ │
│ │ 基于您的知识库提供智能问答                   │ │
│ │                                              │ │
│ │ 能力标签：                                   │ │
│ │ [📚 知识问答] [📊 文档分析] [🌐 联网搜索]   │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ ┌─ 对话区（可滚动）───────────────────────────┐ │
│ │                                              │ │
│ │  [欢迎页 / 对话消息列表]                     │ │
│ │                                              │ │
│ │  👤 用户消息（右对齐，主题色背景）           │ │
│ │                                              │ │
│ │  🤖 Agent 回答（左对齐，白色背景）           │ │
│ │     ├─ 检索状态卡片                          │ │
│ │     ├─ 深度思考过程（可折叠）                │ │
│ │     ├─ 正文内容（Markdown）                  │ │
│ │     ├─ 引用来源卡片                          │ │
│ │     └─ 操作按钮 [复制] [评价]                │ │
│ │                                              │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ ┌─ 快捷提问标签（对话区底部）─────────────────┐ │
│ │ [总结核心观点] [对比分析] [提取数据]         │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ ┌─ 输入区 ────────────────────────────────────┐ │
│ │ [📎 附件] [文本输入区...]         [发送 ➤]  │ │
│ │ Enter 发送 · Shift+Enter 换行               │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ ┌─ 历史面板（覆盖层，点击历史按钮时显示）─────┐ │
│ │ [搜索] [会话列表] [关闭]                     │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```

### 6.2 面板交互

| # | 交互 | 规则 |
|---|------|------|
| 1 | 显隐切换 | 点击页面顶部「Agent」按钮切换面板显隐 |
| 2 | 宽度调整 | 拖拽左侧边缘调整宽度，最小 280px，最大 700px |
| 3 | 拖拽手柄 | 鼠标悬停左边缘时显示拖拽手柄，拖拽时高亮 |
| 4 | 收起按钮 | 点击顶部 − 按钮收起面板 |

---

## 七、数据模型

### 7.1 Thread（会话）

```json
{
  "thread_id": "UUID",
  "user_id": "string",
  "title": "string (≤20字)",
  "created_at": "datetime",
  "updated_at": "datetime",
  "message_count": "number",
  "status": "active | archived"
}
```

### 7.2 Run（单轮对话）

```json
{
  "run_id": "UUID",
  "thread_id": "UUID",
  "sequence": "number (轮次序号)",
  "user_message": {
    "content": "string",
    "attachments": [
      { "file_id": "string", "name": "string", "source": "kb | local" }
    ],
    "timestamp": "datetime"
  },
  "assistant_message": {
    "content": "string (Markdown)",
    "thinking_process": "string | null (深度思考过程)",
    "search_steps": [
      { "type": "rag | web | thinking", "status": "done", "summary": "string" }
    ],
    "sources": [
      { "name": "string", "from": "知识库 | 联网搜索", "quote": "string", "url": "string | null" }
    ],
    "timestamp": "datetime"
  }
}
```

### 7.3 Rating（评价）

```json
{
  "rating_id": "UUID",
  "thread_id": "string",
  "run_id": "string",
  "score": "number (1-10)",
  "suggestion": "string | null",
  "created_at": "datetime"
}
```

### 7.4 User Memory（用户记忆）

```json
{
  "user_id": "string",
  "profile": {
    "role": "string (职业角色)",
    "department": "string",
    "level": "string",
    "industry": "string"
  },
  "preferences": {
    "response_length": "concise | moderate | detailed",
    "response_style": "professional | casual | structured",
    "interested_topics": ["string"],
    "frequently_accessed_files": ["file_id"]
  },
  "feedback_summary": {
    "avg_score": "number",
    "total_ratings": "number",
    "common_suggestions": ["string"]
  }
}
```

---

## 八、性能指标

| 指标 | 目标值 | 说明 |
|------|--------|------|
| 首 Token 延迟 | ≤ 3s | 从发送到首个字符输出 |
| RAG 检索延迟 | ≤ 1s | 知识库检索完成时间 |
| WebSearch 延迟 | ≤ 2s | 联网搜索完成时间 |
| 深度思考延迟 | ≤ 8s | 复杂问题思考完成时间 |
| 流式输出速度 | 30-50 字符/s | 打字机效果速度 |
| 短期记忆窗口 | 8K tokens | 上下文容量 |
| 引用准确率 | ≥ 95% | 引用来源与原文匹配度 |
| 会话加载时间 | ≤ 500ms | 切换历史会话的加载时间 |

---

## 九、附录

### 附录 A：消息类型枚举

| 类型 | role | 说明 |
|------|------|------|
| 用户消息 | user | 用户发送的问题 |
| Agent 回答 | assistant | AI 生成的回答 |
| 系统提示 | system | 系统级提示信息 |
| 检索状态 | status | 检索过程状态展示 |
| 深度思考 | thinking | 思考过程展示 |

### 附录 B：来源类型枚举

| 类型 | from 值 | 图标 | 主题色 | 背景色 |
|------|---------|------|--------|--------|
| 知识库 | 知识库 | 📚 书本 SVG | #6C5CE7（紫） | #F0EDFF |
| 联网搜索 | 联网搜索 | 🌐 地球 SVG | #0369A1（蓝） | #F0F9FF |

### 附录 C：评分等级说明

| 分数区间 | 等级 | 说明 |
|---------|------|------|
| 9-10 | 优秀 | 回答准确、完整、有深度 |
| 7-8 | 良好 | 回答基本满足需求 |
| 5-6 | 一般 | 回答部分有用，有改进空间 |
| 3-4 | 较差 | 回答不够准确或完整 |
| 1-2 | 很差 | 回答无法满足需求 |

### 附录 D：Agent 意图分类

| 意图类型 | 路由策略 | 示例 |
|---------|---------|------|
| 知识检索 | RAG 优先 | "Q3营收是多少？" |
| 实时信息 | WebSearch 优先 | "最新的AI行业趋势" |
| 深度分析 | Deep Thinking | "对比分析两个季度的差异" |
| 文件操作 | 工具调用 | "总结这份文件" |
| 闲聊 | 直接回答 | "你好" |