Vue 3 重构 Dify 聊天前端：项目搭建与基础架构

整体数据流

用户输入 → ChatView → sendChatMessageSSE() → Dify API
↑ ↓
messages 数组 ← SSE 事件流（message/agent_thought/workflow）
↓
MarkdownRenderer → 实时渲染 AI 回复

1. 项目初始化

1.1 创建项目

npm create vite@latest dify-chat -- --template vue-ts
cd dify-chat
npm install

1.2 安装依赖

# 核心依赖
npm install vue-router pinia axios element-plus @element-plus/icons-vue
# Markdown 与代码高亮
npm install marked highlight.js dompurify
# 开发依赖
npm install -D sass @types/dompurify

1.3 Vite 配置

vite.config.ts 是整个项目的构建核心：

import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd())
  return {
    // 支持子路径部署（如 /chat-app/）
    base: env.VITE_APP_NGINX_SUB_PATH || '/',
    plugins: [vue()],
    css: {
      preprocessorOptions: {
        scss: {
          api: 'modern-compiler' // 使用现代 SCSS 编译器
        }
      }
    },
    resolve: {
      alias: {
        '@': '/src' // 路径别名，import xx from '@/utils/xx'
      }
    },
    server: {
      port: 3001,
      proxy: {
        // 开发环境将 /api 请求代理到后端
        '/api': {
          target: 'http://localhost:9000',
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, '')
        }
      }
    }
  }
})

关键设计决策：

• 代理配置：前端 3001 端口，后端 9000 端口。开发时所有 /api/* 请求自动转发到后端，避免跨域问题。
• 路径别名：@/ 映射到 src/，让导入路径更清晰。
• 子路径部署：通过环境变量 VITE_APP_NGINX_SUB_PATH 控制 base path，适配不同部署环境。

1.4 环境变量

创建 .env 文件：

VITE_APP_TITLE=AI 智能助手
VITE_API_BASE_URL=/api
VITE_APP_NGINX_SUB_PATH=/

TypeScript 类型声明 src/env.d.ts：

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  readonly VITE_API_BASE_URL: string
  readonly VITE_APP_NGINX_SUB_PATH: string
}

2. TypeScript 类型体系设计

类型设计是整个项目的基础。我们把所有聊天相关的类型集中在 src/api/chat.ts 中定义。

2.1 消息类型

// 前端使用的消息结构
export interface Message {
  id: string
  role: 'user' | 'assistant'
  content: string
  createAt?: number
  parentMessageId?: string
  messageFiles?: MessageFile[]
  agentThoughts?: AgentThought[]
  workflow_process?: WorkflowProcess
  feedback?: Feedback
  citation?: Citation[]
}

// 后端返回的消息结构（需要转换）
export interface BackendMessage {
  id: string
  conversationId: string
  parentMessageId: string
  inputs: Record<string, any>
  query: string // 用户问题
  answer: string // AI 回答
  messageFiles: MessageFile[]
  feedback: Feedback | null
  retrieverResources: any[]
  agentThoughts: AgentThought[]
  createdAt: number
  status: string
  error: string | null
}

为什么要区分 Message 和 BackendMessage？

后端返回的是'一轮对话'的结构（包含 query + answer），而前端渲染需要拆分为 user 和 assistant 两条独立消息。这个转换在 getMessages 函数中完成。

2.2 文件与附件

export interface MessageFile {
  id: string
  type: string // 'image' | 'document' 等
  url: string
  filename?: string
  size?: number
}

2.3 Agent 思考过程

export interface AgentThought {
  id: string
  thought: string // 思考内容
  tool?: string // 调用的工具名称
  tool_input?: string // 工具输入参数
  observation?: string // 工具执行结果
  message_files?: MessageFile[]
  created_at?: number
}

2.4 工作流追踪

export interface WorkflowProcess {
  status: string // 'running' | 'succeeded' | 'failed'
  tracing: WorkflowNode[]
}

export interface WorkflowNode {
  id: string
  node_id: string
  title: string // 节点名称，如'大模型'、'知识检索'
  status: string // 'running' | 'succeeded' | 'failed'
  inputs?: any
  outputs?: any
  elapsed_time?: number // 执行耗时（秒）
}

2.5 用户反馈

export interface Feedback {
  rating: 'like' | 'dislike' | null
  content?: string // 详细反馈内容
}

2.6 引用来源

export interface Citation {
  position: number
  document_id: string
  document_name: string
  data_source_type: string
  source_url?: string
}

2.7 请求与响应类型

export interface ChatRequest {
  appId: string
  query: string
  conversationId?: string // 有值表示继续已有会话
  inputs?: Record<string, any>
  files?: string[] // 已上传文件的 URL 列表
}

2.8 SSE 回调接口

这是整个流式聊天的核心类型定义——通过回调函数把不同类型的 SSE 事件分发到对应的处理逻辑：

export interface SSECallbacks {
  onMessage: (content: string, taskId?: string, messageId?: string) => void
  onThought: (thought: AgentThought) => void
  onFile: (file: MessageFile) => void
  onMessageEnd: (data: { messageId: string; conversationId: string; citation?: Citation[]; feedback?: Feedback }) => void
  onWorkflowStarted: (data: { workflowRunId: string; taskId: string; conversationId: string }) => void
  onNodeStarted: (node: WorkflowNode) => void
  onNodeFinished: (node: WorkflowNode) => void
  onWorkflowFinished: (data: { status: string; conversationId: string }) => void
  onTTSChunk: (audio: string) => void
  onSuggestedQuestions: (questions: string[]) => void
  onError: (error: string) => void
  onDone: () => void
}

这种设计的好处：SSE 解析逻辑与 UI 更新逻辑完全解耦。sendChatMessageSSE 函数只负责解析 SSE 流并触发回调，而 ChatView 组件通过回调函数决定如何更新 UI。

3. 路由与认证

3.1 路由设计

src/router/index.ts：

import { createRouter, createWebHistory } from 'vue-router'
import { getInfo, ssoLogin } from '@/api/user'
import { useUserStore } from '@/stores/user'

const router = createRouter({
  history: createWebHistory(import.meta.env.VITE_APP_NGINX_SUB_PATH),
  routes: [
    {
      path: '/',
      redirect: '/error?message=请从安溪专区访问'
    },
    {
      path: '/chat/:appId', // 动态路由，支持多应用
      name: 'Chat',
      component: () => import('@/views/ChatView.vue') // 懒加载
    },
    {
      path: '/error',
      name: 'Error',
      component: () => import('@/views/ErrorView.vue')
    }
  ]
})

设计要点：

• /chat/:appId 使用动态路由，同一个前端可以对接不同的 AI 应用（每个应用有不同的 prompt、模型配置等）。
• 路由懒加载（() => import()），首屏不会加载所有页面代码。
• 根路径重定向到错误页，强制用户从指定入口访问。

3.2 SSO 单点登录

通过路由守卫 beforeEach 实现 SSO 认证流程：

router.beforeEach(async (to, from, next) => {
  const userStore = useUserStore()
  const ssoApp = to.query.appid as string
  const ssoCode = to.query.code as string
  let token = userStore.token // 开发环境自动 mock

  if (import.meta.env.DEV) {
    const devToken = 'eyJhbGciOiJIUzI1NiJ9...'
    userStore.setToken(devToken)
    userStore.setUserInfo({ ssoUserName: 'dev_user', nickName: '开发测试用户' })
    token = devToken
  }

  if (ssoApp && ssoCode && !token) {
    try {
      // 1. 用 SSO code 换取 token
      const newToken = await ssoLogin(ssoApp, ssoCode)
      userStore.setToken(newToken)
      // 2. 获取用户信息
      const userInfo = await getInfo()
      userStore.setUserInfo(userInfo)
      // 3. 去掉 URL 中的 code 参数，刷新路由
      const query = { ...to.query }
      delete query.code
      next({ ...to, query, replace: true })
    } catch (error) {
      next({ path: '/error', query: { message: 'SSO 登录失败，请重试' } })
    }
  } else if (!token && to.path !== '/error') {
    next({ path: '/error', query: { message: '未登录，请从门户网站进入' } })
  } else {
    next()
  }
})

SSO 认证流程图：

门户入口 → 带 appid + code 参数访问 /chat/xxx
↓
beforeEach 拦截 → 检测到 code
↓
ssoLogin(appid, code) → 获取 token
↓
getInfo() → 获取用户信息
↓
存储 token + userInfo → 重定向（去掉 code 参数）
↓
进入 ChatView 正常聊天

4. HTTP 客户端封装

4.1 Axios 实例

src/utils/request.ts：

import axios from 'axios'
import { ElMessage, ElMessageBox } from 'element-plus'
import { TOKEN_KEY, useUserStore } from '@/stores/user'

const request = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL, // '/api'
  timeout: 120000 // 2 分钟超时，AI 响应可能较慢
})

4.2 请求拦截器

核心功能：自动注入 Bearer Token。

request.interceptors.request.use((config) => {
  const token = localStorage.getItem(TOKEN_KEY)
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
}, (error) => Promise.reject(error))

这里直接从 localStorage 读取 token，而不是从 Pinia store 读取，是为了避免循环依赖问题（store 还未初始化时就需要发请求）。

4.3 响应拦截器

统一处理后端返回的业务错误码：

request.interceptors.response.use(
  (res) => {
    const code = res.data.code || 200
    const msg = errorCode[code] || res.data.msg || errorCode['default']
    // 二进制数据直接返回
    if (res.request.responseType === 'blob' || res.request.responseType === 'arraybuffer') {
      return res.data
    }
    const userStore = useUserStore()
    if (code === 401) {
      // 认证过期 → 清除登录状态 + 弹窗提示
      userStore.logout()
      return ElMessageBox.alert('登录状态已过期，请重新从门户点击访问！', '认证失败').then(() => Promise.reject('无效的会话'))
    } else if (code === 500) {
      ElMessage.error(msg)
      return Promise.reject(new Error(msg))
    } else if (code === 601) {
      ElMessage.warning(msg)
      return Promise.reject('error')
    } else if (code !== 200) {
      ElMessage.error(msg)
      return Promise.reject('error')
    } else {
      return res.data.data // 只返回业务数据
    }
  },
  (error) => {
    ElMessage.error(error)
    return Promise.reject(error)
  }
)

关键设计：

• 响应拦截器已经'解包'了后端响应，API 函数拿到的直接就是 data 字段的值。
• 401 时自动清除用户状态，引导用户重新登录。
• 二进制数据（文件下载）特殊处理，直接返回完整 response。

4.4 API 函数示例

有了封装好的 request，API 函数写起来非常简洁：

// src/api/app.ts
export const getAppById = async (id: string): Promise<AppInfo> => {
  return await request.get(`/app/${id}`)
}

// src/api/user.ts
export const ssoLogin = async (ssoApp: string, ssoCode: string): Promise<string> => {
  return await request.get('/public/login/ssoLogin', {
    params: { ssoApp, ssoCode }
  })
}

export const getInfo = async (): Promise<UserInfo> => {
  return await request.get('/user/getInfo')
}

5. Pinia Store 设计

5.1 用户状态管理

src/stores/user.ts — 使用 Composition API 风格（defineStore + setup 函数）：

import { defineStore } from 'pinia'
import { ref } from 'vue'

export const TOKEN_KEY = 'ai-token'
export const USER_INFO_KEY = 'ai-userInfo'

export const useUserStore = defineStore('user', () => {
  const userInfo = ref<UserInfo | null>(null)
  const token = ref<string>('')

  // 设置 Token → 同时持久化到 localStorage
  const setToken = (value: string) => {
    token.value = value
    localStorage.setItem(TOKEN_KEY, value)
  }

  // 设置用户信息 → 同步持久化
  const setUserInfo = (info: UserInfo) => {
    userInfo.value = info
    localStorage.setItem(USER_INFO_KEY, JSON.stringify(info))
  }

  // 从 localStorage 恢复（页面刷新后）
  const initFromStorage = () => {
    const storedToken = localStorage.getItem(TOKEN_KEY)
    const storedUserInfo = localStorage.getItem(USER_INFO_KEY)
    if (storedToken) token.value = storedToken
    if (storedUserInfo) {
      try {
        userInfo.value = JSON.parse(storedUserInfo)
      } catch {
        userInfo.value = null
      }
    }
  }

  // 登出 → 清空所有
  const logout = () => {
    userInfo.value = null
    token.value = ''
    localStorage.removeItem(TOKEN_KEY)
    localStorage.removeItem(USER_INFO_KEY)
  }

  return {
    userInfo,
    token,
    setToken,
    setUserInfo,
    initFromStorage,
    logout
  }
})

设计要点：

• Token 和 UserInfo 同时存在内存（ref）和 localStorage 中。内存保证响应式，localStorage 保证刷新后不丢失。
• initFromStorage 在应用启动时调用（main.ts 中），确保路由守卫能拿到 token。

5.2 会话状态管理

src/stores/conversation.ts — 管理会话列表和消息：

import { defineStore } from 'pinia'
import { computed, ref } from 'vue'
import {
  getConversations,
  getMessages,
  deleteConversation as deleteConversationApi,
  pinConversation as pinConversationApi,
  unpinConversation as unpinConversationApi,
  updateConversationName
} from '@/api/chat'

export const useConversationStore = defineStore('conversation', () => {
  // === 状态 ===
  const appId = ref<string>('')
  const conversations = ref<ConversationItem[]>([])
  const pinnedConversations = ref<ConversationItem[]>([])
  const currentConversationId = ref<string>('')
  const currentMessages = ref<any[]>([])
  const isLoading = ref(false)
  const isLoadingMessages = ref(false)

  // === 计算属性 ===
  // 置顶 + 普通合并后的完整列表
  const allConversations = computed(() => [...pinnedConversations.value, ...conversations.value])

  // 当前选中的会话对象
  const currentConversation = computed(() => allConversations.value.find(c => c.id === currentConversationId.value))

  // === 核心方法 ===
  // 加载会话列表
  const loadConversations = async () => {
    if (!appId.value) return
    isLoading.value = true
    try {
      conversations.value = await getConversations(appId.value, 30)
    } finally {
      isLoading.value = false
    }
  }

  // 切换会话 → 加载该会话的消息
  const switchConversation = async (conversationId: string) => {
    if (conversationId === currentConversationId.value) return
    currentConversationId.value = conversationId
    currentMessages.value = []
    if (conversationId) await loadMessages(conversationId)
  }

  // 加载消息 → 关键转换：BackendMessage → Message
  const loadMessages = async (conversationId: string) => {
    if (!appId.value) return
    isLoadingMessages.value = true
    try {
      currentMessages.value = await getMessages(appId.value, conversationId)
    } finally {
      isLoadingMessages.value = false
    }
  }

  // 创建新会话
  const createNewConversation = () => {
    currentConversationId.value = ''
    currentMessages.value = []
  }

  // 删除会话 → 从列表移除 + 如果是当前会话则切换
  const deleteConversation = async (conversationId: string) => {
    await deleteConversationApi(conversationId)
    conversations.value = conversations.value.filter(c => c.id !== conversationId)
    pinnedConversations.value = pinnedConversations.value.filter(c => c.id !== conversationId)
    if (currentConversationId.value === conversationId) {
      createNewConversation()
    }
  }

  // 流式聊天时的实时更新方法
  const updateCurrentConversationId = (conversationId: string) => {
    currentConversationId.value = conversationId
  }

  const addMessage = (message: any) => {
    currentMessages.value.push(message)
  }

  const updateLastMessage = (content: string, extras?: any) => {
    const lastMsg = currentMessages.value[currentMessages.value.length - 1]
    if (lastMsg) {
      lastMsg.content = content
      Object.assign(lastMsg, extras)
    }
  }

  return {
    // 状态
    appId,
    conversations,
    pinnedConversations,
    currentConversationId,
    currentMessages,
    isLoading,
    isLoadingMessages,
    // 计算属性
    currentConversation,
    allConversations,
    // 方法
    setAppId,
    loadConversations,
    switchConversation,
    createNewConversation,
    deleteConversation,
    updateCurrentConversationId,
    addMessage,
    updateLastMessage,
    renameConversation,
    pinConversation,
    unpinConversation
  }
})

架构决策：

1. 会话分两组管理（pinned / normal），计算属性合并展示。置顶操作就是数组间的移动。
2. 消息更新使用 updateLastMessage，这是 SSE 流式更新的关键。每个 message 事件到达时，只需更新最后一条消息的 content。
3. addMessage + updateLastMessage 组合使用：发送消息时先 addMessage 一个空的 assistant 消息占位，然后 SSE 回调不断 updateLastMessage 追加内容。

5.3 后端消息 → 前端消息的转换

这个转换发生在 src/api/chat.ts 的 getMessages 函数中：

export const getMessages = async (appId: string, conversationId: string): Promise<Message[]> => {
  const backendMessages: BackendMessage[] = await request.post('/chat/message/messages', {
    appId,
    conversationId,
    limit: 50
  })
  const messages: Message[] = []
  backendMessages.forEach(m => {
    // 后端一轮对话 = 一条 BackendMessage
    // 前端需要拆成 user + assistant 两条 Message
    messages.push({
      id: `${m.id}-user`,
      role: 'user',
      content: m.query, // 用户问题
      createAt: m.createdAt,
      messageFiles: m.messageFiles
    })
    messages.push({
      id: `${m.id}-assistant`,
      role: 'assistant',
      content: m.answer, // AI 回答
      createAt: m.createdAt,
      agentThoughts: m.agentThoughts,
      feedback: m.feedback || undefined,
      messageFiles: m.messageFiles
    })
  })
  return messages
}

小结

上篇我们完成了：

1. 项目脚手架 — Vite + Vue 3 + TypeScript + Element Plus
2. 类型体系 — 覆盖消息、文件、工作流、Agent 思考等所有业务实体
3. 认证流程 — SSO 单点登录 + 路由守卫
4. HTTP 封装 — 自动 Token 注入 + 统一错误处理
5. 状态管理 — 用户 Store + 会话 Store，支持 localStorage 持久化

下一篇预告：中篇将深入核心功能——SSE 流式聊天的完整实现、ChatView 组件的核心逻辑、Markdown 渲染、文件上传和会话管理。