gimc-ai-agent

AI 智能客服 Vue3 组件，基于 RAG 知识库的智能问答系统。

安装

1. 安装组件

npm install gimc-ai-agent

2. 安装前置依赖

本组件依赖 element-plus，请确保你的项目中已安装：

npm install element-plus @element-plus/icons-vue

⚠️ 重要配置提示 为避免循环依赖问题，必须在你的项目的 vite.config.ts 中配置 chunkSplitPlugin.customSplitting，将 gimc-ai-agent 与 element-plus 打包在一起：

// vite.config.ts
import { chunkSplitPlugin } from 'vite-plugin-chunk-split'

export default defineConfig({
  plugins: [
    chunkSplitPlugin({
      customSplitting: {
        // 将 gimc-ai-agent 与 element-plus 打包在一起，避免循环依赖
        'element-vendor': [/node_modules\/(element-plus|gimc-ai-agent)/],
        // 使用负向前瞻排除已单独拆分的包
        'vendor': [/node_modules\/(?!(element-plus|gimc-ai-agent))/],
      }
    })
  ]
})

3. 配置 main.ts

在项目入口文件中引入 Element Plus 和组件样式：

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import 'gimc-ai-agent/dist/style.css'

const app = createApp(App)
app.use(ElementPlus)
app.mount('#app')

4. 配置环境（可选）

组件默认使用生产环境配置。有两种方式配置环境：

方式1：通过 prop 传递（推荐）

<template>
  <gimc-ai-agent
    :rag-knowledge-id="1"
    :token="token"
    :environment="env"
  />
</template>

<script setup>
import { computed } from 'vue'

// 根据环境变量自动切换
const env = computed(() => import.meta.env.MODE)
</script>

方式2：全局配置

// main.ts
import { envConfigManager } from 'gimc-ai-agent'

// 设置为开发环境
envConfigManager.setEnvironment('development')

// 或根据环境变量自动切换
if (import.meta.env.DEV) {
  envConfigManager.setEnvironment('development')
}

注意：如果同时使用两种方式，prop 方式的优先级更高，会覆盖全局配置。

5. 在组件中使用

<template>
  <!-- 需要配合登录状态控制显示 -->
  <gimc-ai-agent
    v-if="isLoggedIn"
    :rag-knowledge-id="1"
    :token="token"
    :environment="environment"
  />
</template>

<script setup lang="ts">
import { ref, computed } from 'vue'
import { GimcAiAgent, type FeedbackData } from 'gimc-ai-agent'

const agentRef = ref()

// 登录状态判断（根据实际业务修改）
const token = computed(() => localStorage.getItem('token') || '')
const isLoggedIn = computed(() => !!token.value)

// 事件监听
const onSend = (msg: string) => {
  console.log('用户发送:', msg)
}

const onFeedback = (data: FeedbackData) => {
  console.log('用户反馈:', data)
  // 上报到后端
}

const onSatisfaction = (score: number) => {
  console.log('满意度评分:', score)
}

// 主动调用方法
const openAgent = () => agentRef.value?.open()
const closeAgent = () => agentRef.value?.close()
const clearMessages = () => agentRef.value?.clearMessages()
</script>

Props

| 属性 | 类型 | 默认值 | 必填 | 说明 | |------|------|--------|------|------| | ragKnowledgeId | number | - | ✅ | RAG 知识库 ID | | token | string | - | ✅ | 外部系统传入的认证 token（优先级高于 localStorage） | | environment | 'development' \| 'production' | 'production' | ✅ | 环境标识（推荐通过 prop 传递，也可通过 envConfigManager 全局设置） | | title | string | '灵犀AI小助手' | - | 标题 | | avatar | string | - | - | 头像 URL | | floatIcon | string | - | - | 悬浮按钮图标 URL | | position | { right?: number; bottom?: number } | - | - | 位置配置 | | width | number | 560 | - | 弹窗宽度（px） | | welcomeText | string | '灵犀AI小助手已全新上线...' | - | 欢迎语 | | idleTimeout | number | 180000 | - | 空闲超时时间（ms） | | typingSpeed | number | 5 | - | 打字机速度（ms） | | showSatisfaction | boolean | true | - | 是否显示满意度评价 | | showFeedback | boolean | true | - | 是否显示反馈功能 |

Events

| 事件 | 参数 | 说明 | |------|------|------| | open | - | 弹窗打开时触发 | | close | - | 弹窗关闭时触发 | | send | message: string | 用户发送消息时触发 | | feedback | FeedbackData | 用户提交反馈时触发 | | satisfaction | score: number | 用户评分时触发（1-5） | | article-click | Article | 点击文章时触发 | | session-end | - | 会话自动结束时触发 |

Slots

| 插槽名 | 说明 | |--------|------| | float-button | 自定义悬浮按钮 | | header | 自定义头部区域 | | welcome | 自定义欢迎区域 | | quick-actions | 自定义快捷操作区域 |

Expose 方法

| 方法 | 说明 | |------|------| | open() | 打开弹窗 | | close() | 关闭弹窗 | | clearMessages() | 清空消息记录 | | sendMessage(content: string) | 主动发送消息 |

登录状态控制

组件本身不包含登录校验逻辑，建议在业务系统中通过 v-if 控制显示：

<template>
  <!-- 方式1：使用 Pinia store -->
  <gimc-ai-agent
    v-if="userStore.isLoggedIn"
    :rag-knowledge-id="1"
    :token="userStore.token"
  />

  <!-- 方式2：使用 computed token 判断 -->
  <gimc-ai-agent
    v-if="!!token"
    :rag-knowledge-id="1"
    :token="token"
  />
</template>

<script setup>
import { computed } from 'vue'
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()
const token = computed(() => localStorage.getItem('token'))
</script>

Token 认证配置

组件支持两种 token 传递方式：

方式1：通过 prop 传递（推荐用于外部系统集成）

当组件被外部系统调用时，可以通过 token prop 传递认证令牌：

<template>
  <gimc-ai-agent
    v-if="token"
    :rag-knowledge-id="1"
    :token="token"
  />
</template>

<script setup>
import { ref } from 'vue'
import { GimcAiAgent } from 'gimc-ai-agent'

// 外部系统传入的 token
const externalToken = ref('your-external-token-here')
</script>

方式2：使用 localStorage（默认兼容）

如果没有传递 token prop，组件会自动从 localStorage 中读取 gimc-ai-agent-token：

// 在登录成功后设置 token
localStorage.setItem('gimc-ai-agent-token', 'your-token-here')

优先级说明：

• 如果同时存在 token prop 和 localStorage 中的 token，优先使用 token prop
• 这样可以确保外部系统集成时的灵活性

环境配置 API

组件提供了环境配置管理器 envConfigManager，用于切换开发/生产环境：

import { envConfigManager } from 'gimc-ai-agent'

// 设置环境
envConfigManager.setEnvironment('development') // 或 'production'

// 获取当前环境
const env = envConfigManager.getEnvironment()

// 获取完整配置
const config = envConfigManager.getConfig()

// 获取具体配置项
const apiUrl = envConfigManager.getApiUrl()
const projectName = envConfigManager.getProjectName()
const tokenName = envConfigManager.getTokenName()

环境配置说明

| 环境 | API URL | 项目名称 | Token 名称 | |------|---------|----------|-----------| | development | http://dev-api.gw.gimccloud.com:32619/lxai-web-api | 省广智能客服 | gimc-ai-agent | | production | https://api.gimccloud.com/lxai-web-api/ | 灵犀AI后台管理 | gimc-lxai-admin-front |

RAG 知识库配置

本组件需要配合 RAG 知识库后端使用。确保：

1. 后端已部署 RAG 知识库服务
2. 创建知识库并获取 ragKnowledgeId
3. 配置好环境（通过 envConfigManager 设置）
4. 确保用户已通过认证（提供有效的 token）

导出内容

组件提供以下导出内容：

组件

import { GimcAiAgent, AiAgent } from 'gimc-ai-agent'
// GimcAiAgent 和 AiAgent 是同一个组件的两个导出名称

类型定义

import type {
  Message,           // 消息类型
  Article,           // 文章类型
  QuickAction,       // 快捷操作类型
  AiResponse,        // AI 响应类型
  FeedbackData,      // 反馈数据类型
  Position,          // 位置配置
  SatisfactionOption,// 满意度选项
  FeedbackTypeOption,// 反馈类型选项
  Environment,       // 环境类型
  ApiConfig          // API 配置接口
} from 'gimc-ai-agent'

工具和配置

import {
  envConfigManager,    // 环境配置管理器
  defaultFloatIcon,    // 默认悬浮按钮图标
  defaultAvatarIcon    // 默认头像图标
} from 'gimc-ai-agent'

Vue 插件方式使用

// main.ts
import { createApp } from 'vue'
import GimcAiAgentPlugin from 'gimc-ai-agent'

const app = createApp(App)
app.use(GimcAiAgentPlugin) // 全局注册为 GimcAiAgent

自定义插槽示例

<gimc-ai-agent v-if="token" :rag-knowledge-id="1" :token="token">
  <template #float-button>
    <div class="custom-button">
      <img src="/custom-icon.png" />
    </div>
  </template>

  <template #welcome>
    <div class="custom-welcome">
      <h2>欢迎使用智能助手</h2>
      <p>我可以帮你解答各种问题</p>
    </div>
  </template>
</gimc-ai-agent>

依赖说明

核心依赖

• axios: ^1.13.2 - HTTP 请求库
• dompurify: 3.3.1 - HTML 内容安全过滤
• highlight.js: ^11.11.1 - 代码高亮
• marked: ^5.1.2 - Markdown 解析

对等依赖（需要项目安装）

• vue: ^3.3.0
• element-plus: ^2.0.0
• @element-plus/icons-vue: ^2.0.0

Node 版本要求

• Node.js >= 16.0.0

License

MIT