gimc-ai-agent

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

Events

Slots

Expose 方法

登录状态控制

组件本身不包含登录校验逻辑，建议在业务系统中通过 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()

环境配置说明

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">
      
    </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