@blueking/ai-ui-sdk 0.3.0-beta.4 → 0.3.0-beta.6

package/README.md

@@ -1,290 +1,290 @@
-# @blueking/ai-ui-sdk
-
-蓝鲸 AI UI SDK 是一个用于快速构建 AI 聊天界面的 Vue 3 组件库。该 SDK 提供了一系列易用的 Hooks 和工具，帮助开发者轻松集成 AI 对话、内容总结、样式管理等功能。
-
-## 安装
-
-```bash
-npm install @blueking/ai-ui-sdk
-# 或
-yarn add @blueking/ai-ui-sdk
-```
-
-## 主要功能
-
-### 1. 聊天功能 (useChat)
-
-`useChat` Hook 提供完整的聊天会话管理能力，包括发送消息、接收回复、管理会话状态等功能。
-
-#### 基本用法
-
-```typescript
-import { useChat } from '@blueking/ai-ui-sdk';
-
-const {
-  currentSession,       // 当前会话信息
-  sessionContents,      // 会话内容列表
-  sendChat,             // 发送消息方法
-  stopChat,             // 停止生成方法
-  setCurrentSession,    // 设置当前会话
-  currentSessionLoading,// 当前会话加载状态
-  reGenerateChat,       // 重新生成回复
-  reSendChat,           // 重新发送消息
-  deleteChat,           // 删除消息
-} = useChat({
-  // 可选回调函数
-  handleStart: (sessionCode, sessionContent) => {
-    // 开始生成回复时的回调
-  },
-  handleText: (sessionCode, sessionContent) => {
-    // 接收到文本时的回调
-  },
-  handleEnd: (sessionCode, sessionContent) => {
-    // 生成完成时的回调
-  },
-  // 请求配置
-  requestOptions: {
-    url: 'https://your-api-endpoint.com',
-    headers: { /* 自定义请求头 */ }
-  }
-});
-
-// 设置当前会话
-setCurrentSession({
-  sessionCode: 'session-1',
-  sessionName: 'My Chat',
-  model: 'gpt-3.5',
-});
-
-// 发送消息
-sendChat({
-  message: '你好，AI 助手',
-  cite: '可选的引用内容',
-});
-
-// 停止生成回复
-stopChat('session-1');
-```
-
-### 2. 内容总结 (useSummary)
-
-`useSummary` Hook 提供文本内容自动总结功能。
-
-```typescript
-import { useSummary } from '@blueking/ai-ui-sdk';
-
-const { summary } = useSummary({
-  handleStart: () => {
-    // 开始总结时的回调
-  },
-  handleEnd: (summaryText) => {
-    // 总结完成时的回调，返回总结文本
-  },
-  handleError: (message, code) => {
-    // 出错时的回调
-  }
-});
-
-// 使用总结功能
-summary({
-  content: '需要总结的长文本内容...',
-  url: 'https://your-summary-api.com',
-  headers: { /* 自定义请求头 */ },
-  model: 'gpt-3.5', // 可选的模型指定
-});
-```
-
-### 3. 点击代理 (useClickProxy)
-
-`useClickProxy` Hook 提供全局点击事件代理，用于处理代码块展开/收起、全屏显示、复制代码、下载文件等功能。
-
-```typescript
-import { useClickProxy } from '@blueking/ai-ui-sdk';
-
-// 在组件挂载前添加全局点击代理，卸载前自动移除
-useClickProxy();
-```
-
-### 4. 样式管理 (useStyle)
-
-`useStyle` Hook 用于引入和管理 SDK 所需的全局样式。在应用入口处调用一次即可。
-
-```typescript
-import { useStyle } from '@blueking/ai-ui-sdk';
-
-// 引入全局样式
-useStyle();
-```
-
-## 类型定义
-
-SDK 提供了丰富的类型定义，以支持 TypeScript 开发。
-
-### 会话类型
-
-```typescript
-// 会话信息
-interface ISession {
-  sessionCode: string;     // 会话编码
-  sessionName: string;     // 会话名称
-  model: string;           // 使用的模型
-  roleInfo?: {             // 角色信息（可选）
-    collectionId: number;
-    collectionName: string;
-    content: ISessionPrompt[];
-    variables: any[];
-  };
-}
-
-// 会话内容
-interface ISessionContent {
-  id?: number;             // 内容ID
-  role: SessionContentRole;// 角色类型
-  content: string;         // 内容文本
-  status?: SessionContentStatus; // 状态
-  sessionCode: string;     // 所属会话编码
-  cite?: string;           // 引用内容
-  time?: string;           // 时间戳
-}
-
-// 快捷方式
-interface ShortCut {
-  label: string;           // 显示文本
-  key: string;             // 唯一标识
-  prompt: string;          // 提示词模板
-  icon?: string;           // 图标（可选）
-}
-```
-
-### 枚举值
-
-```typescript
-// 会话内容角色
-enum SessionContentRole {
-  Ai = 'ai',               // AI 回复
-  User = 'user',           // 用户消息
-  System = 'system',       // 系统消息
-  // ... 更多角色类型
-}
-
-// 会话内容状态
-enum SessionContentStatus {
-  Fail = 'fail',           // 失败
-  Loading = 'loading',     // 加载中
-  Success = 'success',     // 成功
-}
-```
-
-## 完整示例
-
-下面是一个完整的使用示例，展示了如何在 Vue 3 组件中集成 SDK：
-
-```vue
-<template>
-  <div class="chat-container">
-    <!-- 消息列表 -->
-    <div class="message-list">
-      <div v-for="message in sessionContents" :key="message.id" class="message">
-        <div class="avatar">
-          {{ message.role === 'user' ? '👤' : '🤖' }}
-        </div>
-        <div class="content">{{ message.content }}</div>
-      </div>
-    </div>
-    
-    <!-- 输入框 -->
-    <div class="input-area">
-      <input 
-        v-model="inputMessage" 
-        @keyup.enter="handleSend"
-        placeholder="请输入消息..."
-      />
-      <button @click="handleSend" :disabled="currentSessionLoading">
-        {{ currentSessionLoading ? '生成中...' : '发送' }}
-      </button>
-      <button v-if="currentSessionLoading" @click="handleStop">停止</button>
-    </div>
-  </div>
-</template>
-
-<script setup lang="ts">
-import { ref } from 'vue';
-import { useChat, useStyle, useClickProxy } from '@blueking/ai-ui-sdk';
-
-// 引入全局样式
-useStyle();
-
-// 添加点击代理
-useClickProxy();
-
-// 初始化聊天功能
-const {
-  currentSession,
-  sessionContents,
-  sendChat,
-  stopChat,
-  setCurrentSession,
-  currentSessionLoading,
-} = useChat({
-  handleStart: () => {
-    console.log('开始生成回复');
-  },
-  handleEnd: () => {
-    console.log('回复生成完成');
-  },
-  requestOptions: {
-    url: 'https://your-chat-api.com',
-  }
-});
-
-// 设置当前会话
-setCurrentSession({
-  sessionCode: 'session-' + Date.now(),
-  sessionName: '新对话',
-  model: 'gpt-3.5',
-});
-
-const inputMessage = ref('');
-
-// 发送消息
-const handleSend = () => {
-  if (!inputMessage.value.trim()) return;
-  
-  sendChat({
-    message: inputMessage.value,
-  });
-  
-  inputMessage.value = '';
-};
-
-// 停止生成
-const handleStop = () => {
-  if (currentSession.value?.sessionCode) {
-    stopChat(currentSession.value.sessionCode);
-  }
-};
-</script>
-```
-
-## 注意事项
-
-1. 确保在应用中只调用一次 `useStyle()` 以避免样式重复注入
-2. `useClickProxy()` 应在组件挂载前调用，会自动在组件卸载时移除事件监听
-3. 发送消息前必须通过 `setCurrentSession()` 设置当前会话
-4. 所有网络请求需要在 `requestOptions` 中配置正确的 API 地址
-
-## 高级功能
-
-SDK 还提供了以下高级功能：
-
-- 支持引用上下文进行提问
-- 支持快捷操作菜单配置
-- 支持代码块的展开/收起、全屏显示、复制、下载
-- 支持响应内容的重新生成和删除
-- 支持会话内容的自动滚动
-
-## 版本兼容性
-
-- 需要 Vue 3.x
-- TypeScript 4.x 或更高版本
-- 现代浏览器（Chrome, Firefox, Safari, Edge）
+# @blueking/ai-ui-sdk
+
+蓝鲸 AI UI SDK 是一个用于快速构建 AI 聊天界面的 Vue 3 组件库。该 SDK 提供了一系列易用的 Hooks 和工具，帮助开发者轻松集成 AI 对话、内容总结、样式管理等功能。
+
+## 安装
+
+```bash
+npm install @blueking/ai-ui-sdk
+# 或
+yarn add @blueking/ai-ui-sdk
+```
+
+## 主要功能
+
+### 1. 聊天功能 (useChat)
+
+`useChat` Hook 提供完整的聊天会话管理能力，包括发送消息、接收回复、管理会话状态等功能。
+
+#### 基本用法
+
+```typescript
+import { useChat } from '@blueking/ai-ui-sdk';
+
+const {
+  currentSession,       // 当前会话信息
+  sessionContents,      // 会话内容列表
+  sendChat,             // 发送消息方法
+  stopChat,             // 停止生成方法
+  setCurrentSession,    // 设置当前会话
+  currentSessionLoading,// 当前会话加载状态
+  reGenerateChat,       // 重新生成回复
+  reSendChat,           // 重新发送消息
+  deleteChat,           // 删除消息
+} = useChat({
+  // 可选回调函数
+  handleStart: (sessionCode, sessionContent) => {
+    // 开始生成回复时的回调
+  },
+  handleText: (sessionCode, sessionContent) => {
+    // 接收到文本时的回调
+  },
+  handleEnd: (sessionCode, sessionContent) => {
+    // 生成完成时的回调
+  },
+  // 请求配置
+  requestOptions: {
+    url: 'https://your-api-endpoint.com',
+    headers: { /* 自定义请求头 */ }
+  }
+});
+
+// 设置当前会话
+setCurrentSession({
+  sessionCode: 'session-1',
+  sessionName: 'My Chat',
+  model: 'gpt-3.5',
+});
+
+// 发送消息
+sendChat({
+  message: '你好，AI 助手',
+  cite: '可选的引用内容',
+});
+
+// 停止生成回复
+stopChat('session-1');
+```
+
+### 2. 内容总结 (useSummary)
+
+`useSummary` Hook 提供文本内容自动总结功能。
+
+```typescript
+import { useSummary } from '@blueking/ai-ui-sdk';
+
+const { summary } = useSummary({
+  handleStart: () => {
+    // 开始总结时的回调
+  },
+  handleEnd: (summaryText) => {
+    // 总结完成时的回调，返回总结文本
+  },
+  handleError: (message, code) => {
+    // 出错时的回调
+  }
+});
+
+// 使用总结功能
+summary({
+  content: '需要总结的长文本内容...',
+  url: 'https://your-summary-api.com',
+  headers: { /* 自定义请求头 */ },
+  model: 'gpt-3.5', // 可选的模型指定
+});
+```
+
+### 3. 点击代理 (useClickProxy)
+
+`useClickProxy` Hook 提供全局点击事件代理，用于处理代码块展开/收起、全屏显示、复制代码、下载文件等功能。
+
+```typescript
+import { useClickProxy } from '@blueking/ai-ui-sdk';
+
+// 在组件挂载前添加全局点击代理，卸载前自动移除
+useClickProxy();
+```
+
+### 4. 样式管理 (useStyle)
+
+`useStyle` Hook 用于引入和管理 SDK 所需的全局样式。在应用入口处调用一次即可。
+
+```typescript
+import { useStyle } from '@blueking/ai-ui-sdk';
+
+// 引入全局样式
+useStyle();
+```
+
+## 类型定义
+
+SDK 提供了丰富的类型定义，以支持 TypeScript 开发。
+
+### 会话类型
+
+```typescript
+// 会话信息
+interface ISession {
+  sessionCode: string;     // 会话编码
+  sessionName: string;     // 会话名称
+  model: string;           // 使用的模型
+  roleInfo?: {             // 角色信息（可选）
+    collectionId: number;
+    collectionName: string;
+    content: ISessionPrompt[];
+    variables: any[];
+  };
+}
+
+// 会话内容
+interface ISessionContent {
+  id?: number;             // 内容ID
+  role: SessionContentRole;// 角色类型
+  content: string;         // 内容文本
+  status?: SessionContentStatus; // 状态
+  sessionCode: string;     // 所属会话编码
+  cite?: string;           // 引用内容
+  time?: string;           // 时间戳
+}
+
+// 快捷方式
+interface ShortCut {
+  label: string;           // 显示文本
+  key: string;             // 唯一标识
+  prompt: string;          // 提示词模板
+  icon?: string;           // 图标（可选）
+}
+```
+
+### 枚举值
+
+```typescript
+// 会话内容角色
+enum SessionContentRole {
+  Ai = 'ai',               // AI 回复
+  User = 'user',           // 用户消息
+  System = 'system',       // 系统消息
+  // ... 更多角色类型
+}
+
+// 会话内容状态
+enum SessionContentStatus {
+  Fail = 'fail',           // 失败
+  Loading = 'loading',     // 加载中
+  Success = 'success',     // 成功
+}
+```
+
+## 完整示例
+
+下面是一个完整的使用示例，展示了如何在 Vue 3 组件中集成 SDK：
+
+```vue
+<template>
+  <div class="chat-container">
+    <!-- 消息列表 -->
+    <div class="message-list">
+      <div v-for="message in sessionContents" :key="message.id" class="message">
+        <div class="avatar">
+          {{ message.role === 'user' ? '👤' : '🤖' }}
+        </div>
+        <div class="content">{{ message.content }}</div>
+      </div>
+    </div>
+    
+    <!-- 输入框 -->
+    <div class="input-area">
+      <input 
+        v-model="inputMessage" 
+        @keyup.enter="handleSend"
+        placeholder="请输入消息..."
+      />
+      <button @click="handleSend" :disabled="currentSessionLoading">
+        {{ currentSessionLoading ? '生成中...' : '发送' }}
+      </button>
+      <button v-if="currentSessionLoading" @click="handleStop">停止</button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useChat, useStyle, useClickProxy } from '@blueking/ai-ui-sdk';
+
+// 引入全局样式
+useStyle();
+
+// 添加点击代理
+useClickProxy();
+
+// 初始化聊天功能
+const {
+  currentSession,
+  sessionContents,
+  sendChat,
+  stopChat,
+  setCurrentSession,
+  currentSessionLoading,
+} = useChat({
+  handleStart: () => {
+    console.log('开始生成回复');
+  },
+  handleEnd: () => {
+    console.log('回复生成完成');
+  },
+  requestOptions: {
+    url: 'https://your-chat-api.com',
+  }
+});
+
+// 设置当前会话
+setCurrentSession({
+  sessionCode: 'session-' + Date.now(),
+  sessionName: '新对话',
+  model: 'gpt-3.5',
+});
+
+const inputMessage = ref('');
+
+// 发送消息
+const handleSend = () => {
+  if (!inputMessage.value.trim()) return;
+  
+  sendChat({
+    message: inputMessage.value,
+  });
+  
+  inputMessage.value = '';
+};
+
+// 停止生成
+const handleStop = () => {
+  if (currentSession.value?.sessionCode) {
+    stopChat(currentSession.value.sessionCode);
+  }
+};
+</script>
+```
+
+## 注意事项
+
+1. 确保在应用中只调用一次 `useStyle()` 以避免样式重复注入
+2. `useClickProxy()` 应在组件挂载前调用，会自动在组件卸载时移除事件监听
+3. 发送消息前必须通过 `setCurrentSession()` 设置当前会话
+4. 所有网络请求需要在 `requestOptions` 中配置正确的 API 地址
+
+## 高级功能
+
+SDK 还提供了以下高级功能：
+
+- 支持引用上下文进行提问
+- 支持快捷操作菜单配置
+- 支持代码块的展开/收起、全屏显示、复制、下载
+- 支持响应内容的重新生成和删除
+- 支持会话内容的自动滚动
+
+## 版本兼容性
+
+- 需要 Vue 3.x
+- TypeScript 4.x 或更高版本
+- 现代浏览器（Chrome, Firefox, Safari, Edge）