gimc-ai-agent 1.0.0

package/README.md

@@ -0,0 +1,299 @@
+# gimc-ai-agent
+
+AI 智能客服 Vue3 组件，基于 RAG 知识库的智能问答系统。
+
+## 安装
+
+### 1. 安装组件
+
+```bash
+npm install gimc-ai-agent
+```
+
+### 2. 安装前置依赖
+
+本组件依赖 `element-plus`，请确保项目中已安装：
+
+```bash
+npm install element-plus @element-plus/icons-vue
+```
+
+### 3. 配置 main.ts
+
+在项目入口文件中引入 Element Plus 和组件样式：
+
+```typescript
+// 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. 在组件中使用
+
+```vue
+<template>
+  <!-- 建议配合登录状态控制显示 -->
+  <GimcAiAgent
+    v-if="isLoggedIn"
+    ref="agentRef"
+    :rag-knowledge-id="1"
+    :token="userToken"
+    title="智能客服"
+    @send="onSend"
+    @feedback="onFeedback"
+    @satisfaction="onSatisfaction"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import { GimcAiAgent } from 'gimc-ai-agent'
+import type { FeedbackData } from 'gimc-ai-agent'
+
+const agentRef = ref()
+
+// 登录状态判断（根据实际业务修改）
+const userToken = computed(() => localStorage.getItem('token') || '')
+const isLoggedIn = computed(() => !!userToken.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>
+```
+
+## 完整安装步骤总结
+
+```bash
+# 1. 安装组件和依赖
+npm install gimc-ai-agent element-plus @element-plus/icons-vue
+
+# 2. 在 main.ts 中配置
+#    - 引入 ElementPlus 并 use
+#    - 引入 'element-plus/dist/index.css'
+#    - 引入 'gimc-ai-agent/dist/style.css'
+
+# 3. 在需要的页面中引入组件使用
+#    import { GimcAiAgent } from 'gimc-ai-agent'
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+|------|------|--------|------|------|
+| `ragKnowledgeId` | `number` | - | ✅ | RAG 知识库 ID |
+| `token` | `string` | - | - | 外部系统传入的认证 token（优先级高于 localStorage） |
+| `title` | `string` | `'灵犀AI小助手'` | - | 标题 |
+| `avatar` | `string` | 内置图标 | - | 头像 URL |
+| `floatIcon` | `string` | 内置图标 | - | 悬浮按钮图标 URL |
+| `position` | `{ right?: number; bottom?: number }` | `{ right: 8, bottom: 24 }` | - | 位置配置（单位：px） |
+| `width` | `number` | `560` | - | 弹窗宽度（单位：px） |
+| `welcomeText` | `string` | `'有任何问题，随时问我～'` | - | 欢迎语 |
+| `idleTimeout` | `number` | `180000` | - | 空闲超时时间（ms） |
+| `typingSpeed` | `number` | `30` | - | 打字机速度（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)` | 主动发送消息 |
+
+## 类型定义
+
+```typescript
+interface Message {
+  role: 'user' | 'assistant'
+  content: string
+  timestamp?: string
+  showFeedback?: boolean
+  feedback?: 'resolved' | 'unresolved' | null
+  suggestions?: string[]
+  isTyping?: boolean
+}
+
+interface Article {
+  title: string
+  url: string
+}
+
+interface QuickAction {
+  label: string
+  icon?: string
+  onClick?: () => void
+  url?: string
+}
+
+interface FeedbackData {
+  messageId: string
+  type: string
+  resolved: boolean
+  detail?: string
+}
+
+interface Position {
+  right?: number
+  bottom?: number
+}
+```
+
+## 登录状态控制
+
+组件本身不包含登录校验逻辑，建议在业务系统中通过 `v-if` 控制显示：
+
+```vue
+<template>
+  <!-- 方式1：使用 Pinia store -->
+  <GimcAiAgent
+    v-if="userStore.isLoggedIn"
+    :rag-knowledge-id="1"
+    :token="userStore.token"
+  />
+
+  <!-- 方式2：使用 computed token 判断 -->
+  <GimcAiAgent
+    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 传递认证令牌：
+
+```vue
+<template>
+  <GimcAiAgent
+    :rag-knowledge-id="1"
+    :token="externalToken"
+  />
+</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`：
+
+```javascript
+// 在登录成功后设置 token
+localStorage.setItem('gimc-ai-agent-token', 'your-token-here')
+```
+
+**优先级说明**：
+- 如果同时存在 `token` prop 和 localStorage 中的 token，优先使用 `token` prop
+- 这样可以确保外部系统集成时的灵活性
+
+## RAG 知识库配置
+
+本组件需要配合 RAG 知识库后端使用。确保：
+
+1. 后端已部署 RAG 知识库服务
+2. 创建知识库并获取 `ragKnowledgeId`
+3. 配置好后端 API 地址（通过环境变量）
+4. 确保用户已通过认证（提供有效的 token）
+
+## 自定义插槽示例
+
+```vue
+<GimcAiAgent :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>
+</GimcAiAgent>
+```
+
+## 后端接口要求
+
+组件会调用以下后端接口（基于配置的 API 地址）：
+
+- `POST /api/rag-knowledge/answer/stream` - 流式问答接口
+- `GET /api/rag-knowledge/session/list` - 获取会话列表
+- `GET /api/rag-knowledge/session/messages` - 获取历史消息
+- `GET /api/rag-knowledge/questions/suggested` - 获取推荐问题
+- `GET /api/rag-knowledge/questions/recommended` - 获取相关问题
+- `POST /api/rag-knowledge/feedback` - 提交反馈
+- `PUT /api/rag-knowledge/feedback` - 更新反馈
+- `DELETE /api/rag-knowledge/feedback/{id}` - 删除反馈
+- `POST /api/rag-knowledge/stop` - 停止生成
+
+## License
+
+MIT

package/dist/App.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/api/request.d.ts

@@ -0,0 +1,33 @@
+import type { AxiosRequestConfig } from 'axios';
+interface RequestConfig extends AxiosRequestConfig {
+    singleThread?: boolean;
+}
+/**
+ * 配置 API
+ */
+export declare function setApiConfig(config: {
+    baseUrl?: string;
+    token?: string;
+    headers?: Record<string, string>;
+}): void;
+/**
+ * 获取当前配置
+ */
+export declare function getApiConfig(): {
+    baseUrl: string;
+    token: string;
+    headers: Record<string, string>;
+};
+/**
+ * 通用请求方法
+ */
+export declare function request<T = any>(config: RequestConfig): Promise<T>;
+/**
+ * GET 请求
+ */
+export declare function get<T = any>(url: string, config?: RequestConfig): Promise<T>;
+/**
+ * POST 请求
+ */
+export declare function post<T = any>(url: string, data?: any, config?: RequestConfig): Promise<T>;
+export default request;

package/dist/assets/icons.d.ts

@@ -0,0 +1,3 @@
+export declare const defaultFloatIcon: string;
+export declare const defaultFloatIconHover: string;
+export declare const defaultAvatarIcon: string;

package/dist/components/AiAgent.vue.d.ts

@@ -0,0 +1,82 @@
+import type { Article, FeedbackData } from '../types';
+type __VLS_Props = {
+    /** RAG 知识库 ID（必填） */
+    ragKnowledgeId: number;
+    /** 标题 */
+    title?: string;
+    /** 头像 URL */
+    avatar?: string;
+    /** 悬浮按钮图标 URL */
+    floatIcon?: string;
+    /** 位置配置 */
+    position?: {
+        right?: number;
+        bottom?: number;
+    };
+    /** 弹窗宽度 */
+    width?: number;
+    /** 欢迎语 */
+    welcomeText?: string;
+    /** 空闲超时时间(ms) */
+    idleTimeout?: number;
+    /** 打字机速度(ms) */
+    typingSpeed?: number;
+    /** 是否显示满意度评价 */
+    showSatisfaction?: boolean;
+    /** 是否显示反馈功能 */
+    showFeedback?: boolean;
+    /** 外部系统传入的 token */
+    token?: string;
+};
+declare var __VLS_1: {}, __VLS_9: {}, __VLS_24: {}, __VLS_125: {};
+type __VLS_Slots = {} & {
+    'float-button'?: (props: typeof __VLS_1) => any;
+} & {
+    header?: (props: typeof __VLS_9) => any;
+} & {
+    welcome?: (props: typeof __VLS_24) => any;
+} & {
+    'quick-actions'?: (props: typeof __VLS_125) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
+    open: () => void;
+    close: () => void;
+    clearMessages: () => void;
+    sendMessage: (content: string) => Promise<void>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    open: () => any;
+    close: () => any;
+    send: (message: string) => any;
+    feedback: (data: FeedbackData) => any;
+    satisfaction: (score: number) => any;
+    "article-click": (article: Article) => any;
+    "session-end": () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onOpen?: (() => any) | undefined;
+    onClose?: (() => any) | undefined;
+    onSend?: ((message: string) => any) | undefined;
+    onFeedback?: ((data: FeedbackData) => any) | undefined;
+    onSatisfaction?: ((score: number) => any) | undefined;
+    "onArticle-click"?: ((article: Article) => any) | undefined;
+    "onSession-end"?: (() => any) | undefined;
+}>, {
+    title: string;
+    position: {
+        right?: number;
+        bottom?: number;
+    };
+    width: number;
+    welcomeText: string;
+    idleTimeout: number;
+    typingSpeed: number;
+    showSatisfaction: boolean;
+    showFeedback: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};