AI 应用开发：Agent 前端设计实战-分屏布局、实时同步的智能体界面Agentic AI 系统前端设计文档 📋 文

Agentic AI 系统前端设计文档

文档概述

本文档详细描述了 Agentic AI 助手系统的最终落地实现情况，包括系统架构、核心流程、状态管理、数据流转、UI交互等各个方面的设计细节。

文档版本: v1.0.0

系统概述

系统定位

Agentic 是一个智能 AI 助手系统，支持用户通过自然语言与 AI 进行对话，AI 能够执行复杂任务、调用工具、生成文档，并提供实时的思考过程和执行状态反馈。

核心能力

智能对话: 支持多轮对话，理解用户意图
任务执行: AI 能够生成待办清单并执行任务
工具调用: 支持文件编辑、代码生成等多种工具
文件管理: 支持文件上传、预览、下载
实时反馈: 流式输出思考过程和执行状态
历史管理: 保存对话历史，支持恢复和继续

系统架构

整体架构图

┌─────────────────────────────────────────────────────────────┐
│                        用户界面层                              │
├─────────────────────────────────────────────────────────────┤
│  agentic-search/          agentic-detail/                    │
│  ├─ index.vue             ├─ [groupId].vue                  │
│  └─ history.vue           └─ (对话详情页)                     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                      组件层 (Components)                       │
├─────────────────────────────────────────────────────────────┤
│  components/agentic/                                         │
│  ├─ SearchInputAgentic.vue        (搜索输入组件)             │
│  ├─ AgenticCaseComponent.vue      (案例展示组件)             │
│  │                                                           │
│  ├─ dialogue/                      (对话窗口)            │
│  │  ├─ DialogueWindow.vue          (对话窗口主组件)          │
│  │  ├─ EnhancedMessageRenderer.vue (消息渲染组件)            │
│  │  ├─ MessageReportDocument.vue   (报告文档组件)            │
│  │  ├─ MessageTodoList.vue         (待办清单组件)            │
│  │  ├─ MessageToolInvocation.vue   (工具调用组件)            │
│  │  ├─ UploadedFilesDisplay.vue    (上传文件展示)            │
│  │  ├─ ProgressBar.vue             (进度条组件)             │
│  │  ├─ SkipStreamButton.vue        (跳过流式按钮)            │
│  │  └─ DownloadFormatDialog.vue    (下载格式对话框)          │
│  │                                                           │
│  └─ agentic-panel/                 (Agentic视窗)         │
│     ├─ AgenticPanel.vue            (视窗主组件)              │
│     ├─ AgenticPanelHeader.vue      (视窗头部)               │
│     ├─ AgenticPanelLeft.vue        (左侧入口组件)            │
│     ├─ AgenticFileManager.vue      (文件管理器)              │
│     ├─ AgenticMdPreview.vue        (Markdown预览)            │
│     ├─ AgenticPdfPreview.vue       (PDF预览)                 │
│     └─ AgenticToolStatusBar.vue    (工具状态栏)              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                     状态管理层 (Stores)                       │
├─────────────────────────────────────────────────────────────┤
│  agentic.ts (业务状态)          agentic-ui.ts (UI状态)       │
│  ├─ 会话管理                    ├─ 布局状态                  │
│  ├─ 处理状态                    ├─ Tab状态                    │
│  ├─ 消息历史                    ├─ 展开/折叠状态             │
│  ├─ 思考流                      ├─ 预览状态                  │
│  ├─ 待办任务                    ├─ 工具结果Tabs             │
│  ├─ 工具调用                    ├─ 文件管理器                │
│  ├─ 文件索引                    └─ 通知状态                  │
│  ├─ 引用信息                                                 │
│  ├─ 会话信息                                                 │
│  ├─ 反馈请求                                                │
│  ├─ 流式数据控制                                            │
│  └─ 模拟流式输出                                            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                     服务层 (Services)                         │
├─────────────────────────────────────────────────────────────┤
│  agentApi.ts                dataTransformers.ts             │
│  ├─ API调用封装             ├─ 数据转换器                  │
│  ├─ 流式数据处理             ├─ 消息转换                    │
│  └─ 错误处理                └─ 类型转换                     
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                     后端 API 层                               │
├─────────────────────────────────────────────────────────────┤
│  /agent/send_message        /agent/chat/{id}/stream          │
│  /agent/chat_history       /agent/preview_file             │
│  /upload                    /agent/list_files ...           │
└─────────────────────────────────────────────────────────────┘

技术栈

前端框架: Vue 3 + Nuxt 3
状态管理: Pinia
类型系统: TypeScript
UI组件: Element Plus
数据流: Server-Sent Events (SSE)
构建工具: Vite

页面结构

1. 搜索首页 (`/agentic-search`)

文件路径: pages/agentic-search/index.vue

功能概述

用户进入系统的首页，提供搜索输入框和案例展示。

核心功能

搜索输入
- 支持文本输入
- 支持文件上传（最多5个文件）
- 支持提示词自动补全
- 支持多种搜索模式（fast/accurate）
案例展示
- 展示推荐案例、研究案例、PPT案例
- 支持Tab切换
- 点击案例跳转到详情页

关键流程

sequenceDiagram
    participant User
    participant SearchPage
    participant AgentStore
    participant Router

    User->>SearchPage: 输入内容/上传文件
    User->>SearchPage: 点击搜索
    SearchPage->>AgentStore: createNewChat()
    AgentStore->>AgentStore: 上传文件(如有)
    AgentStore->>AgentStore: 发送消息API
    AgentStore->>AgentStore: 保存chatId
    SearchPage->>Router: navigateTo(/agentic-detail/{chatId})
    Router->>SearchPage: 跳转到详情页

代码实现要点

// 创建新会话（不启动流数据）
const chatId = await agentStore.createNewChat({
    content: params.text,
    files: params.files,
    mode: params.mode,
    domains: params.type
})

// 跳转到详情页
await navigateTo(`/agentic-detail/${chatId}`)

2. 历史记录页 (`/agentic-search/history`)

文件路径: pages/agentic-search/history.vue

功能概述

展示用户的历史对话记录，支持查看、删除操作。

核心功能

历史列表
- 分页加载历史记录
- 显示对话标题、更新时间
- 支持滚动加载更多
操作功能
- 点击记录跳转到详情页
- 支持删除历史记录
- 显示加载状态

关键流程

sequenceDiagram
    participant User
    participant HistoryPage
    participant API
    participant Router

    User->>HistoryPage: 进入历史页
    HistoryPage->>API: getChatHistoryList()
    API-->>HistoryPage: 返回历史列表
    HistoryPage->>HistoryPage: 渲染列表
    
    User->>HistoryPage: 点击历史记录
    HistoryPage->>Router: push(/agentic-detail/{id}?source=history)
    
    User->>HistoryPage: 删除记录
    HistoryPage->>API: deleteChatHistory(id)
    API-->>HistoryPage: 删除成功
    HistoryPage->>HistoryPage: 更新列表

3. 对话详情页 (`/agentic-detail/[groupId]`)

文件路径: pages/agentic-detail/[groupId].vue

功能概述

核心对话页面，展示对话内容、AI思考过程、工具执行状态等。

页面布局

┌─────────────────────────────────────────────────────────┐
│  头部: 返回按钮 + 标题 + 文件管理器按钮                    │
├──────────────────────────┬──────────────────────────────┤
│                          │                              │
│   对话窗口 (左侧)         │   Agentic面板 (右侧)          │
│                          │                              │
│  - 消息列表              │  - Thinking Tab              │
│  - 输入框                │  - Todo Tab                  │
│  - 文件上传              │  - Tools Tab                 │
│                          │  - Files Tab                 │
│                          │                              │
│                          │  - 文件预览                  │
│                          │  - 工具结果预览               │
│                          │                              │
└──────────────────────────┴──────────────────────────────┘

核心功能

对话展示
- 用户消息和AI消息
- 支持Markdown渲染
- 支持文件预览
- 支持工具调用展示
流式数据接收
- 实时接收AI思考过程
- 实时更新工具执行状态
- 实时更新待办清单
文件管理
- 文件上传
- 文件预览（PDF/Markdown/Text）
- 文件下载
工具预览
- 自动打开工具执行预览
- 显示工具执行状态
- 显示工具执行结果

关键流程

页面初始化流程:

sequenceDiagram
    participant Page
    participant AgentStore
    participant API
    participant UIStore

    Page->>Page: onMounted
    Page->>UIStore: reset() (重置UI状态)
    Page->>Page: 获取route.params.groupId
    
    alt 案例来源 (source=case)
        Page->>AgentStore: startSimulatedStream(groupId)
        AgentStore->>API: getAgentChatHistory()
        API-->>AgentStore: 返回完整历史
        AgentStore->>AgentStore: 模拟流式输出
    else 历史来源 (source=history)
        Page->>AgentStore: initializeSession(groupId)
        AgentStore->>API: getAgentChatHistory()
        API-->>AgentStore: 返回历史数据
        alt 未完成对话 (status=0)
            AgentStore->>AgentStore: startAgenticStream()
        end
    else 新会话 (从首页跳转)
        Page->>AgentStore: startAgenticStream(groupId)
    end

消息发送流程:

sequenceDiagram
    participant User
    participant Page
    participant AgentStore
    participant API

    User->>Page: 输入内容/上传文件
    User->>Page: 点击发送
    Page->>AgentStore: sendMessage()
    AgentStore->>AgentStore: 上传文件(如有)
    AgentStore->>AgentStore: 添加用户消息到列表
    AgentStore->>API: sendMessage()
    API-->>AgentStore: 返回chatId
    AgentStore->>AgentStore: startAgenticStream(chatId)
    AgentStore->>API: streamChatMessages()
    
    loop 流式数据接收
        API-->>AgentStore: 流式数据片段
        AgentStore->>AgentStore: handleStreamData()
        AgentStore->>AgentStore: 更新消息/思考/工具状态
    end
    
    API-->>AgentStore: [DONE]
    AgentStore->>AgentStore: 结束流接收

状态管理设计

Store 架构

系统采用双 Store 架构，将业务状态和UI状态完全分离：

┌─────────────────────────────────────────────────────────┐
│                    Agent Store                           │
│                  (业务状态管理)                          │
├─────────────────────────────────────────────────────────┤
│  • 会话状态 (sessionId, threadGroupId)                   │
│  • 消息历史 (messages)                                  │
│  • 思考流 (thinkingStream)                              │
│  • 待办任务 (todoList)                                  │
│  • 工具调用 (toolCalls)                                 │
│  • 文件索引 (indexedFiles)                             │
│  • 流式数据处理                                          │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                  Agentic UI Store                        │
│                    (UI状态管理)                          │
├─────────────────────────────────────────────────────────┤
│  • 布局状态 (面板宽度、显示状态)                         │
│  • Tab状态 (activeTab, tabBadges)                       │
│  • 展开/折叠状态                                         │
│  • 预览状态 (文件预览、工具预览)                         │
│  • 通知状态                                              │
└─────────────────────────────────────────────────────────┘

Agent Store 详细设计

文件路径: stores/agentic.ts

核心状态

// 会话状态
const sessionId = ref<string | null>(null)
const threadGroupId = ref<string | null>(null)
const threadId = ref<string | null>(null)

// 处理状态
const isProcessing = ref(false)
const isLoadingData = ref(false)

// 消息历史
const messages = ref<Message[]>([])

// 思考流
const thinkingStream = ref<Thought[]>([])

// 待办任务
const todoList = ref<TodoTask[]>([])

// 工具调用
const toolCalls = ref<ToolCall[]>([])

// 文件索引
const indexedFiles = ref<FileItem[]>([])

// 引用信息
const allCitations = ref<Citation[]>([])

核心方法

会话管理
- initializeSession(groupId?): 初始化会话
- loadHistoryByGroupId(groupId): 加载历史记录
- loadAgentChatHistory(chatId, checkResume): 加载聊天历史
消息发送
- createNewChat(params): 创建新会话（首页使用）
- sendMessage(params): 发送消息并启动流接收
流式数据处理
- startAgenticStream(chatId, options): 开始接收流数据
- handleStreamData(data): 处理流式数据
- processMessageWithTransformer(data, chatId): 使用转换器处理消息
模拟流式输出
- startSimulatedStream(chatId): 启动模拟流（案例来源）
- playNextSimulatedMessage(): 播放下一条消息
- skipSimulatedStream(): 跳过模拟，直接渲染全部
操作控制
- abort(): 中止当前操作
- reset(): 重置所有状态

数据流转

graph TD
    A[用户操作] --> B[Agent Store]
    B --> C{操作类型}
    C -->|发送消息| D[上传文件]
    C -->|加载历史| E[获取历史数据]
    C -->|流式接收| F[SSE连接]
    
    D --> G[发送消息API]
    E --> H[数据转换器]
    F --> I[流式数据处理]
    
    G --> J[返回chatId]
    H --> K[转换为前端格式]
    I --> L[实时更新状态]
    
    J --> M[启动流接收]
    K --> N[更新Store状态]
    L --> N
    
    N --> O[UI自动更新]

Agentic UI Store 详细设计

文件路径: stores/agentic-ui.ts

核心状态

// 布局状态
const leftPanelWidth = ref(60)
const rightPanelWidth = ref(40)
const showAgenticPanel = ref(false)
const isFullscreen = ref(false)

// Tab状态
const activeAgenticTab = ref<AgenticTab>('thinking')
const tabBadges = ref<Record<AgenticTab, number>>({...})

// 展开/折叠状态
const isThinkingExpanded = ref(true)
const expandedTodoIds = ref<Set<string>>(new Set())
const expandedToolCallIds = ref<Set<string>>(new Set())

// 预览状态
const previewState = ref<PreviewState>({
    isPreviewMode: false,
    currentFile: null,
    previewType: 'none'
})

// 文件管理器
const showFileManager = ref(false)
const fileManagerChatId = ref<string | null>(null)

核心方法

布局控制
- resizePanels(leftWidth): 调整面板宽度
- toggleAgenticPanel(): 切换面板显示
- showPanel() / hidePanel(): 显示/隐藏面板
Tab管理
- switchAgenticTab(tab): 切换Tab
- updateTabBadge(tab, count): 更新Tab角标
- incrementTabBadge(tab): 增加Tab角标
预览管理
- openFilePreview(file): 打开文件预览
- closeFilePreview(): 关闭文件预览
- goBackPreview() / goForwardPreview(): 预览历史导航
文件管理器
- openFileManager(chatId): 打开文件管理器
- closeFileManager(): 关闭文件管理器

API 服务层设计

Agent API Service

文件路径: composables/agentic/agentApi.ts

核心接口

消息发送
```
sendMessage(params: SendMessageParams): Promise<SendMessageResponse>
```
- 创建新会话或继续现有对话
- 支持文件附件
- 返回chatId和msgId

流式数据接收

streamChatMessages(
    chatId: string,
    callback: StreamDataCallback,
    options?: { newOnly?: boolean; signal?: AbortSignal }
): Promise<void>

使用SSE接收流式数据
支持中止控制
支持新消息/全部消息模式

历史记录

getAgentChatHistory(chatId: string): Promise<AgentChatHistory>
getChatHistoryList(params: ChatHistoryListParams): Promise<ChatHistoryListResponse>

文件操作

uploadFiles(files: File[]): Promise<FileUploadResponse>
previewFile(params: PreviewFileParams): Promise<PreviewFileResponse>
downloadFile(params: DownloadFileParams): Promise<Blob>
listFiles(params: ListFilesParams): Promise<ListFilesResponse>

流式数据处理

SSE数据格式:

data: {"type": 1, "status_info": {...}}
data: {"type": 2, "chat_message": {...}}
data: {"type": 3, "citations": [...]}
data: {"type": 4, "title": "..."}
data: [DONE]

数据类型:

type: 1: 状态信息
type: 2: 聊天消息
type: 3: 引用信息
type: 4: 标题更新

数据转换器

文件路径: composables/agentic/dataTransformers.ts

转换器架构

AgentDataTransformer (主转换器)
├── MessageTransformer (消息转换)
├── ThoughtTransformer (思考流转换)
├── ToolCallTransformer (工具调用转换)
├── FileTransformer (文件转换)
└── TodoTransformer (待办任务转换)

核心转换逻辑

消息转换 (MessageTransformer)
- 用户消息: msg_type: 0
- AI文本消息: msg_type: 1
- AI思考消息: msg_type: 2 (包含工具调用)
- AI反问消息: msg_type: 3
- 任务完成消息: msg_type: 9
工具调用处理
- 工具类型判断 (tool_type)
- 工具状态转换 (tool_call_status)
- 子任务处理 (parent_msg_id)
数据去重
- 使用 processedMessageIds 跟踪已处理消息
- 合并相同 msg_id 的消息更新

消息处理流程

消息类型体系

Message
├── UserMessage (用户消息)
│   ├── content: string
│   └── files?: UploadedFile[]
│
└── AIMessage (AI消息)
    ├── aiMessageType: 1 | 2 | 3 | 9
    ├── content: string
    ├── todoInfo?: TodoInfo (tool_type=3)
    ├── toolInvocation?: ToolInvocation (其他工具)
    ├── reportDocument?: ReportDocument (最终文件)
    └── metadata: MessageMetadata

消息渲染流程

graph TD
    A[收到消息] --> B{消息类型}
    B -->|用户消息| C[渲染用户消息组件]
    B -->|AI消息| D{aiMessageType}
    
    D -->|1: 文本消息| E[渲染Markdown内容]
    D -->|2: 思考消息| F{是否有工具调用}
    D -->|3: 反问消息| G[渲染待办清单]
    D -->|9: 完成消息| H[渲染报告文档]
    
    F -->|tool_type=3| I[渲染待办清单]
    F -->|其他工具| J[渲染工具调用组件]
    
    J --> K{工具状态}
    K -->|running| L[显示执行中状态]
    K -->|completed| M[显示执行结果]
    
    I --> N[实时更新待办项]
    L --> O[自动打开预览窗]
    M --> P[更新预览窗内容]

工具调用处理

工具类型

待办生成工具 (tool_type: 3)
- 使用 TodoList 组件渲染
- 实时更新待办项状态
文件编辑工具 (file_editor_tool, str_replace_editor_tool)
- 使用 ToolInvocation 组件渲染
- 显示执行状态和结果
任务完成工具 (task_done)
- 显示最终输出文件
- 提供下载功能

子任务处理

通过 parent_msg_id 机制实现工具调用的层级关系：

// 子任务消息处理
if (parentMsgId && agentMessage.type === 2 && chatMsg.tool_call) {
    const parentMessage = messages.value.find(m => m.id === parentMsgId)
    if (parentMessage && parentMessage.toolInvocation) {
        // 添加子任务到父工具
        parentMessage.toolInvocation.subTasks.push({
            name: toolCall.tool_call_name,
            status: 'running',
            description: subTaskDescription
        })
    }
}

文件管理流程

文件上传流程

sequenceDiagram
    participant User
    participant Component
    participant AgentStore
    participant API

    User->>Component: 选择文件
    Component->>Component: 验证文件类型和大小
    Component->>Component: 添加到上传列表
    Component->>Component: 显示预览
    
    User->>Component: 点击发送
    Component->>AgentStore: sendMessage({files})
    AgentStore->>API: uploadFiles(files)
    API-->>AgentStore: 返回file_url列表
    AgentStore->>API: sendMessage({attachments})
    API-->>AgentStore: 返回chatId

文件预览流程

sequenceDiagram
    participant User
    participant Page
    participant API
    participant UIStore

    User->>Page: 点击文件/文档
    Page->>API: previewFile({chat_id, file_path})
    API-->>Page: 返回预览数据
    
    alt PDF文件
        Page->>Page: 解析PDF页面数据
        Page->>UIStore: openFilePreview({type: 'pdf'})
    else Markdown/Text文件
        Page->>Page: 解析文本内容
        Page->>UIStore: openFilePreview({type: 'md'})
    end
    
    UIStore->>UIStore: 更新previewState
    UIStore->>UIStore: showPanel()

文件管理器

功能:

浏览工作空间文件
支持目录导航
支持文件预览
支持文件下载

实现:

使用 listFiles API 获取文件列表
使用树形结构展示目录
集成文件预览功能

UI交互设计

响应式布局

// 小屏幕自动隐藏面板
const isSmallScreen = computed(() => windowWidth.value < 900)

watch(isSmallScreen, (isSmall) => {
    if (isSmall && showAgenticPanel.value) {
        uiStore.hidePanel()
    }
})

工具预览自动打开

触发条件:

工具开始执行 (toolStatus: 'running')
工具数据更新 (描述或结果变化)
有新结果数据

实现逻辑:

watch(
    () => messages.value,
    (newMessages) => {
        const isStreaming = isProcessing.value || isLoadingData.value
        if (!isStreaming) return
        
        newMessages.forEach((message) => {
            if (!message.toolInvocation) return
            
            const isToolStarting = toolStatus === 'running' && 
                                  currentSnapshot?.toolStatus !== 'running'
            
            if (isToolStarting) {
                openOrUpdateToolPreview(message, false)
            }
        })
    },
    { deep: true }
)

Tab角标管理

// 当有新思考时
incrementTabBadge('thinking')

// 当有新待办时
incrementTabBadge('todo')

// 当有新工具时
incrementTabBadge('tools')

// 切换到Tab时清除角标
switchAgenticTab('thinking') // 自动清除thinking角标

数据流转全景

完整数据流

graph TB
    subgraph user[&#34;用户操作&#34;]
        A1[&#34;输入文本&#34;]
        A2[&#34;上传文件&#34;]
        A3[&#34;点击发送&#34;]
    end
    
    subgraph frontend[&#34;前端处理&#34;]
        B1[&#34;文件验证&#34;]
        B2[&#34;添加到Store&#34;]
        B3[&#34;调用API&#34;]
    end
    
    subgraph backend[&#34;后端处理&#34;]
        C1[&#34;接收请求&#34;]
        C2[&#34;处理任务&#34;]
        C3[&#34;生成响应&#34;]
    end
    
    subgraph stream[&#34;流式数据&#34;]
        D1[&#34;SSE连接&#34;]
        D2[&#34;数据片段&#34;]
        D3[&#34;数据解析&#34;]
    end
    
    subgraph state[&#34;状态更新&#34;]
        E1[&#34;更新消息&#34;]
        E2[&#34;更新思考流&#34;]
        E3[&#34;更新工具状态&#34;]
        E4[&#34;更新待办清单&#34;]
    end
    
    subgraph ui[&#34;UI渲染&#34;]
        F1[&#34;渲染消息&#34;]
        F2[&#34;渲染思考流&#34;]
        F3[&#34;渲染工具状态&#34;]
        F4[&#34;打开预览窗&#34;]
    end
    
    A1 --> B1
    A2 --> B1
    A3 --> B2
    B2 --> B3
    B3 --> C1
    C1 --> C2
    C2 --> C3
    C3 --> D1
    D1 --> D2
    D2 --> D3
    D3 --> E1
    D3 --> E2
    D3 --> E3
    D3 --> E4
    E1 --> F1
    E2 --> F2
    E3 --> F3
    E3 --> F4
    E4 --> F3

状态同步机制

单向数据流: 用户操作 → Store更新 → UI自动更新
响应式绑定: 使用 storeToRefs 实现响应式
计算属性: 使用 computed 缓存计算结果
监听器: 使用 watch 处理副作用

性能优化策略

1. 流式数据处理优化

增量更新: 只更新变化的部分，不重新渲染整个列表
防抖处理: 对频繁更新的状态进行防抖
虚拟滚动: 长列表使用虚拟滚动（如需要）

2. 状态管理优化

按需更新: 只更新必要的状态
计算属性缓存: 使用computed缓存计算结果
状态分离: 业务状态和UI状态分离，减少不必要的响应

3. 组件优化

懒加载: 大型组件使用懒加载
条件渲染: 使用v-if减少DOM节点
事件防抖: 对频繁触发的事件进行防抖

4. 网络优化

请求合并: 合并多个小请求
缓存策略: 对历史数据使用缓存
超时控制: 设置合理的超时时间

错误处理机制

错误类型

网络错误: 请求失败、超时
业务错误: API返回错误码
数据错误: 数据格式不正确
流式错误: SSE连接中断

错误处理策略

// 统一错误处理
try {
    await agentStore.sendMessage(params)
} catch (error: any) {
    if (error?.response?.status === 429) {
        // 限流错误
        handleRateLimitError(error.message)
    } else if (error?.response?.status === 404) {
        // 资源不存在
        ElMessage.error('资源不存在')
    } else {
        // 其他错误
        ElMessage.error('操作失败，请重试')
        console.error('Error:', error)
    }
}

重试机制

流式数据: 自动重连机制
文件上传: 支持断点续传（如需要）
API请求: 支持重试（如需要）

关键实现细节

1. 消息去重机制

// 使用 processedMessageIds 跟踪已处理消息
const processedMessageIds = ref<Set<string>>(new Set())

// 处理消息前检查
if (messageId && processedMessageIds.value.has(messageId)) {
    // 更新现有消息，不创建新消息
    updateExistingMessage(message)
    return
}

// 记录已处理
processedMessageIds.value.add(messageId)

2. 工具状态快照

// 使用快照检测状态变化
const toolMessageSnapshots = ref<Map<string, {
    toolStatus?: 'running' | 'completed' | 'failed'
    toolDescription?: string
    hasResult?: boolean
}>>(new Map())

// 检测变化
const hasDescriptionChanged = currentSnapshot?.toolDescription !== toolDescription
const hasNewResult = hasResult && !currentSnapshot?.hasResult

3. 模拟流式输出

// 案例来源使用模拟流式输出
const startSimulatedStream = async (chatId: string) => {
    // 加载完整历史
    const chatHistory = await AgentApiService.getAgentChatHistory(chatId)
    
    // 转换数据
    const transformed = AgentDataTransformer.transformChatHistory(chatHistory)
    
    // 暂存完整数据
    simulationHistoryData.value = transformed
    
    // 定时器逐条播放
    simulationTimer = setInterval(() => {
        playNextSimulatedMessage()
    }, intervalMs)
}

4. 文件预览状态管理

// 预览状态包含多种类型
const previewState = ref<PreviewState>({
    isPreviewMode: false,
    currentFile: null,
    previewType: 'none', // 'pdf' | 'md' | 'docx' | 'none'
    currentMessageId: '', // 工具预览时使用
    toolDescription: '',
    toolResultContent: null
})

调试与监控

日志策略

开发环境: 详细日志
生产环境: 错误日志
关键操作: 操作日志

性能监控

流式数据接收速度
消息渲染性能
API响应时间
内存使用情况

扩展点设计

1. 插件化架构

消息渲染插件: 支持自定义消息渲染
工具调用插件: 支持自定义工具展示
文件预览插件: 支持自定义文件类型预览

2. 主题定制

颜色主题: 支持自定义颜色
布局主题: 支持自定义布局
组件主题: 支持自定义组件样式

3. 功能扩展

多会话管理: 支持同时管理多个会话
消息搜索: 支持搜索历史消息
导出功能: 支持导出对话记录

最佳实践

1. Store使用

// ✅ 正确: 使用 storeToRefs
const { messages, isProcessing } = storeToRefs(agentStore)

// ❌ 错误: 直接解构
const { messages, isProcessing } = agentStore // 失去响应性

2. 状态更新

// ✅ 正确: 使用Store方法
agentStore.sendMessage(params)

// ❌ 错误: 直接修改状态
agentStore.messages.push(newMessage) // 应该使用Store方法

3. 错误处理

// ✅ 正确: 完整的错误处理
try {
    await agentStore.sendMessage(params)
} catch (error) {
    console.error('Error:', error)
    ElMessage.error('发送失败')
}

// ❌ 错误: 忽略错误
await agentStore.sendMessage(params) // 没有错误处理

数据模型

核心类型定义

// 消息类型
interface Message {
    id: string
    type: 'user' | 'ai'
    content: string
    timestamp: number
    files?: UploadedFile[]
    aiMessageType?: 1 | 2 | 3 | 9
    todoInfo?: TodoInfo
    toolInvocation?: ToolInvocation
    reportDocument?: ReportDocument
    metadata?: MessageMetadata
}

// 思考流类型
interface Thought {
    id: string
    content: string
    timestamp: number
    type: 'analysis' | 'action' | 'summary' | 'thinking'
}

// 待办任务类型
interface TodoTask {
    id: string
    title: string
    description?: string
    status: 'pending' | 'inProgress' | 'completed' | 'failed'
    progress: number
    timestamp: number
}

// 工具调用类型
interface ToolCall {
    id: string
    name: string
    description: string
    status: 'pending' | 'running' | 'completed' | 'failed'
    result: any
    parameters: Record<string, any>
    timestamp: number
    metadata?: ToolCallMetadata
}

总结

系统特点

模块化设计: 清晰的模块划分，职责明确
类型安全: 完整的TypeScript类型系统
响应式设计: 流畅的用户体验
可扩展性: 预留扩展接口，便于迭代
性能优化: 多种优化策略，保证流畅运行

技术亮点

双Store架构: 业务状态和UI状态分离
流式数据处理: 实时反馈，用户体验好
数据转换器: 统一的数据转换逻辑
自动预览: 智能打开工具预览窗
模拟流式输出: 案例展示的流畅体验

后续优化方向

性能优化: 进一步优化大列表渲染
功能扩展: 添加更多工具支持
用户体验: 优化交互细节
错误处理: 完善错误处理和重试机制
测试覆盖: 增加单元测试和集成测试

文档维护: 本文档应随系统更新而更新，确保文档与代码同步。

AI 应用开发：Agent 前端设计实战-分屏布局、实时同步的智能体界面

Agentic AI 系统前端设计文档

文档概述

系统概述

系统定位

核心能力

系统架构

整体架构图

技术栈

页面结构

1. 搜索首页 (/agentic-search)

功能概述

核心功能

关键流程

代码实现要点

2. 历史记录页 (/agentic-search/history)

功能概述

核心功能

关键流程

3. 对话详情页 (/agentic-detail/[groupId])

功能概述

页面布局

核心功能

关键流程

状态管理设计

Store 架构

Agent Store 详细设计

核心状态

核心方法

数据流转

Agentic UI Store 详细设计

核心状态

核心方法

API 服务层设计

Agent API Service

核心接口

流式数据处理

数据转换器

转换器架构

核心转换逻辑

消息处理流程

消息类型体系

消息渲染流程

工具调用处理

工具类型

子任务处理

文件管理流程

文件上传流程

文件预览流程

文件管理器

UI交互设计

响应式布局

工具预览自动打开

Tab角标管理

数据流转全景

完整数据流

状态同步机制

性能优化策略

1. 流式数据处理优化

2. 状态管理优化

3. 组件优化

4. 网络优化

错误处理机制

错误类型

错误处理策略

重试机制

关键实现细节

1. 消息去重机制

2. 工具状态快照

3. 模拟流式输出

4. 文件预览状态管理

调试与监控

日志策略

性能监控

扩展点设计

1. 插件化架构

2. 主题定制

3. 功能扩展

最佳实践

1. Store使用

1. 搜索首页 (`/agentic-search`)

2. 历史记录页 (`/agentic-search/history`)

3. 对话详情页 (`/agentic-detail/[groupId]`)