@blueking/ai-blueking 0.5.0-beta.7 → 0.5.0

package/README.md

@@ -1,644 +1,374 @@
-# AI 小鲸使用指南
+# AI 小鲸 (AI Blueking) 使用文档
 
-## 目录
+## 简介
 
-- [简介](#简介)
-- [安装](#安装)
-- [特性](#特性)
-- [使用指南](#使用指南)
-- [开发调试](#开发调试)
+AI 小鲸是一个智能对话组件，支持 Vue2/Vue3 框架，提供丰富的交互功能和灵活的配置选项。只需简单配置，即可快速接入智能对话能力，提升应用的用户体验。
 
-## 简介
+## 特性
 
-AI 小鲸是一个智能对话组件,支持 Vue2/Vue3 框架,提供了丰富的交互功能和灵活的配置选项。
+- **实时对话**：支持流式输出，让对话更自然流畅
+- **内容引用**：选中文本即可快速引用并提问
+- **快捷操作**：支持预设常用功能和提示词
+- **可拖拽界面**：自由调整窗口位置和大小
+- **开箱即用**：传入 Agent 地址即可快速接入业务
+- **跨框架支持**：同时支持 Vue2 和 Vue3 框架
 
 ## 安装
 
 ```bash
-npm i @blueking/ai-blueking
+npm install @blueking/ai-blueking
 ```
 
-## 特性
-
-- 支持 popup 弹框唤起
-- 支持引用提问功能 
-- 支持快捷提问(当前支持翻译、解释功能)
-- 支持使用 `enablePopup` 属性控制弹框唤起(默认为 true)
-
-## 使用指南
+或
 
-### 基础配置
+```bash
+yarn add @blueking/ai-blueking
+```
 
-#### 组件显示/隐藏控制
+## 基本使用
 
-**注意：0.3.0 版本重大变更**
+### Vue 3
 
-- 使用 `v-model:is-show` 绑定变量控制组件显示状态
-- **不再使用 `v-if` 进行控制**
+```vue
+<template>
+  <div>
+    <button @click="showAI">打开 AI 小鲸</button>
+    
+    <AIBlueking 
+      ref="aiBlueking"
+      :url="apiUrl"
+      @show="handleShow"
+      @close="handleClose"
+    />
+  </div>
+</template>
 
-#### 消息发送回调
+<script lang="ts" setup>
+import { ref } from 'vue';
+import AIBlueking from '@blueking/ai-blueking';
+import '@blueking/ai-blueking/dist/vue3/style.css';
 
-**注意：0.3.0 版本重大变更**
+const aiBlueking = ref(null);
+const apiUrl = 'https://your-api-endpoint.com/assistant/';
 
-`handleSend _callback`函数现在接收一个对象参数:
+const showAI = () => {
+  console.log('AI 小鲸已显示');
+};
 
-```typescript
-interface ISendData {
-  content: string;  // 用户输入的内容
-  cite?: string;    // 引用的内容(可选)
-  prompt?: string;  // 使用的 prompt 模板(可选)
-}
+const handleClose = () => {
+  console.log('AI 小鲸已关闭');
+};
+</script>
 ```
 
-以下展示了如何处理新的 handleSend 回调，完整示例请参考 [Stream 模式](#stream-模式-vue3)
+### Vue 2
 
-```typescript
-const handleSend = (args: ISendData) => {
-  // 记录当前消息记录
-  const chatHistory = [...messages.value];
-
-  // 添加用户消息
-  messages.value.push({
-    role: 'user',
-    content: args.content,
-    cite: args.cite,
-  });
+```vue
+<template>
+  <div>
+    <button @click="showAI">打开 AI 小鲸</button>
+    
+    <AIBlueking 
+      ref="aiBlueking"
+      :url="apiUrl"
+      @show="handleShow"
+      @close="handleClose"
+    />
+  </div>
+</template>
 
-  // 根据参数构造输入内容
-  const input = args.prompt 
-    ? args.prompt                           // 如果有 prompt，直接使用
-    : args.cite 
-      ? `${args.content}: ${args.cite}`     // 如果有 cite，拼接 content 和 cite
-      : args.content;                       // 否则只使用 content
-
-  // 调用 AI 流式对话
-  // 注：id 是唯一标识当前流，调用 chatHelper.stop 时需要传入
-  chatHelper.stream(
-    {
-      inputs: {
-        input,
-        chat_history: chatHistory,
-      },
+<script>
+import AIBlueking from '@blueking/ai-blueking/vue2';
+import '@blueking/ai-blueking/dist/vue2/style.css';
+
+export default {
+  components: {
+    AIBlueking
+  },
+  data() {
+    return {
+      apiUrl: 'https://your-api-endpoint.com/assistant/'
+    };
+  },
+  methods: {
+    showAI() {
+      this.$refs.aiBlueking.handleShow();
+    },
+    handleShow() {
+      console.log('AI 小鲸已显示');
     },
-    1,
-  );
+    handleClose() {
+      console.log('AI 小鲸已关闭');
+    }
+  }
 };
+</script>
 ```
 
-### 模板渲染
-
-#### 知识库列表渲染
+## 属性 (Props)
+
+| 属性名 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| url | String | '' | AI 服务接口地址，必须设置 |
+| enablePopup | Boolean | true | 是否启用选中文本后的弹出操作窗口 |
+| shortcuts | Array | [...] | 快捷操作列表 |
+| prompts | Array | [] | 预设提示词列表 |
+
+### shortcuts 格式示例
+
+```javascript
+[
+  {
+    label: '解释',
+    key: 'explanation',
+    prompt: '解释一下内容： {{ SELECTED_TEXT }}',
+    icon: 'icon-explanation'
+  },
+  {
+    label: '翻译',
+    key: 'translate',
+    prompt: '翻译一下内容： {{ SELECTED_TEXT }}',
+    icon: 'icon-translate'
+  }
+]
+```
 
-可使用特定模板渲染匹配的知识库列表,示例:
+### prompts 格式示例
 
-```html
-<section class="knowledge-tips">
-  <i class="ai-blueking-icon ai-blueking-angle-up"></i>
-  <span class="knowledge-summary">
-    <i class="ai-blueking-icon ai-blueking-help-document"></i>
-    引用 4 篇资料作为参考
-  </span>
-  <a href="xxx" target="_blank" class="knowledge-link">
-    1. vivo 容器平台如何实现资源超卖方案
-    <i class="ai-blueking-icon ai-blueking-cc-jump-link"></i>
-  </a>
-</section>
+```javascript
+[
+  '请概括这段内容的主要观点',
+  '请帮我分析这段文字中的问题',
+  '请用简单的语言解释这个概念'
+]
 ```
 
-#### 交互元素渲染
+## 事件 (Events)
 
-AI 小鲸支持渲染可点击的交互式 HTML 元素。以下是如何实现这一功能的指南：
+| 事件名 | 参数 | 描述 |
+|--------|------|------|
+| show | - | AI 小鲸窗口显示时触发 |
+| close | - | AI 小鲸窗口关闭时触发 |
+| stop | - | 停止生成内容时触发 |
+| shortcut-click | shortcut: ShortCut | 点击快捷操作时触发，返回所点击的快捷操作对象 |
 
-- **渲染可点击元素**：使用带有 `ai-clickable` 类的 HTML 元素来创建可交互的组件。点击这些元素时，会触发组件的 `ai-click` 事件，并将 `data-ai` 属性的数据传递给事件处理程序。
+## 方法 (Methods)
 
-- **示例**：
+| 方法名 | 参数 | 返回值 | 描述 |
+|--------|------|--------|------|
+| handleShow | - | - | 显示 AI 小鲸窗口 |
+| handleStop | - | - | 停止当前正在生成的内容 |
+| sendChat | options: {message, cite, shortcut} | - | 发送消息到 AI 小鲸 |
+| handleShortcutClick | shortcut: ShortCut | - | 处理快捷操作点击 |
 
-  ```html
-  <button data-ai="{ type: 'button', data: 'xxx' }" class="ai-clickable">可点击的按钮</button>
-  <a data-ai="{ type: 'link', data: 'link url' }" class="ai-clickable" href="void">可点击的链接</a>
-  ```
+## 高级用法
 
-- **事件处理**：点击后，`ai-click` 事件被触发。您可以通过 `data-ai` 属性传递数据，例如：
-
-  ```javascript
-  handleCustomButtonClick(dataAIValue) {
-    // 假设 'aiRef' 是组件的引用
-    const val = dataAIValue; //从 data-ai 属性获取的数据'
-  
-    ... // 业务处理逻辑，比如以下将`data-ai`上的字符串赋值到输入框
-    aiRef.value?.setInputMessage(val); 
-  }
-  ```
+### Vue 3 快捷操作演示
 
-这样，业务逻辑可以根据传递的数据进行二次处理，比如将 `data-ai` 上的字符串值设置到输入框中。
+```vue
+<template>
+  <div>
+    <div class="article">
+      <h3>AI 技术的发展与应用</h3>
+      <p>{{ articleContent }}</p>
+    </div>
+    
+    <div class="quick-actions">
+      <button @click="quickActions('解释', '解释一下这段内容：', articleTitle)">
+        解释标题
+      </button>
+      <button @click="quickActions('翻译', '翻译成英文：', articleTitle)">
+        翻译标题
+      </button>
+    </div>
+    
+    <AIBlueking ref="aiBlueking" :url="apiUrl" />
+  </div>
+</template>
 
-### 使用示例
+<script lang="ts" setup>
+import { ref } from 'vue';
+import AIBlueking from '@blueking/ai-blueking';
+import '@blueking/ai-blueking/dist/vue3/style.css';
 
-#### Stream 模式 (Vue3)
+const aiBlueking = ref(null);
+const apiUrl = 'https://your-api-endpoint.com/assistant/';
+const articleTitle = 'AI 技术的发展与应用';
+const articleContent = '人工智能技术在近年来取得了突飞猛进的发展...';
 
-不同框架，组件引入方式不同，具体可参考下面的的例子。这里使用 vue3 项目为例，来展示 stream 模式交互
+const quickActions = (label, promptPrefix, cite) => {
+  aiBlueking.value?.handleShow();
+  
+  aiBlueking.value?.sendChat({
+    message: label,
+    cite,
+    shortcut: {
+      label,
+      key: label.toLowerCase(),
+      prompt: `${promptPrefix} {{ SELECTED_TEXT }}`,
+      icon: 'icon-explanation'
+    }
+  });
+};
+</script>
+```
 
-参考完整示例代码:
+### Vue 2 快捷操作演示
 
 ```vue
 <template>
-  <AIBlueking
-    v-model:is-show="isShow"
-    :loading="loading"
-    :messages="messages"
-    @clear="handleClear"
-    @send="handleSend"
-    @stop="handleStop"
-  />
+  <div>
+    <div class="article">
+      <h3>AI 技术的发展与应用</h3>
+      <p>{{ articleContent }}</p>
+    </div>
+    
+    <div class="quick-actions">
+      <button @click="quickActions('解释', '解释一下这段内容：', articleTitle)">
+        解释标题
+      </button>
+      <button @click="quickActions('翻译', '翻译成英文：', articleTitle)">
+        翻译标题
+      </button>
+    </div>
+    
+    <AIBlueking ref="aiBlueking" :url="apiUrl" />
+  </div>
 </template>
 
-<script lang="ts" setup>
-  import { ref } from 'vue';
-  import AIBlueking, { ChatHelper, RoleType, MessageStatus, isThinking } from '@blueking/ai-blueking';
-  import '@blueking/ai-blueking/dist/vue3/style.css';
-
-  interface ISendData {
-    content: string; // 用户输入的内容
-    cite?: string;   // 引用的内容
-    prompt?: string; // 使用的 prompt 模板
-  }
-
-  const loading = ref(false);
-  const messages = ref([]);
-  const isShow = ref(false);
-
-  // 聊天开始
-  const handleStart = (id: number | string) => {
-    loading.value = true;
-    messages.value.push({
-      role: RoleType.Assistant,
-      content: '内容正在生成中...',
-      status: MessageStatus.Loading,
-    });
-  };
-
-  // 接收消息
-  const handleReceiveMessage = (message: string, id: number | string, cover?: boolean) => {
-    const currentMessage = messages.value.at(-1);
-    if (currentMessage?.status === MessageStatus.Loading) {
-      // 如果是loading状态，直接覆盖
-      currentMessage.content = message;
-      currentMessage.status = MessageStatus.Success;
-    } else if (currentMessage?.status === MessageStatus.Success) {
-      // 根据 cover 参数决定是追加还是覆盖
-      currentMessage.content = cover ? message : currentMessage.content + message;
+<script>
+import AIBlueking from '@blueking/ai-blueking/vue2';
+import '@blueking/ai-blueking/dist/vue2/style.css';
+
+export default {
+  components: {
+    AIBlueking
+  },
+  data() {
+    return {
+      apiUrl: 'https://your-api-endpoint.com/assistant/',
+      articleTitle: 'AI 技术的发展与应用',
+      articleContent: '人工智能技术在近年来取得了突飞猛进的发展...'
+    };
+  },
+  methods: {
+    quickActions(label, promptPrefix, cite) {
+      
+      this.$refs.aiBlueking.handleShow(); // 显示AI小鲸
+      
+      this.$refs.aiBlueking.sendChat({ // 主动调用发送消息
+        message: label,
+        cite,
+        shortcut: {
+          label,
+          key: label.toLowerCase(),
+          prompt: `${promptPrefix} {{ SELECTED_TEXT }}`
+        }
+      });
     }
-  };
-
-  // 聊天结束
-  const handleEnd = (id: number | string) => {
-    loading.value = false;
-    const currentMessage = messages.value.at(-1);
-    // 在 loading 状态或思考状态下终止时，标记为错误
-    if (currentMessage?.status === MessageStatus.Loading || isThinking(currentMessage?.content || '')) {
-      currentMessage.content = '聊天内容已中断';
-      currentMessage.status = MessageStatus.Error;
-    }
-  };
-
-  // 错误处理
-  const handleError = (message: string, code: string | number, id: number | string) => {
-    if (message.includes('user authentication failed')) {
-      // 未登录，跳转登录
-      const loginUrl = new URL(process.env.BK_LOGIN_URL);
-      loginUrl.searchParams.append('c_url', location.origin);
-      window.location.href = loginUrl.href;
-    } else {
-      // 处理错误消息
-      const currentMessage = messages.value.at(-1);
-      currentMessage.status = MessageStatus.Error;
-      currentMessage.content = message;
-      loading.value = false;
-    }
-  };
-
-  const prefix = process.env.BK_API_URL_TMPL.replace('{api_name}', '<网关名>').replace('http', 'https');
-  const chatHelper = new ChatHelper(
-    `${prefix}/prod/bk_plugin/plugin_api/assistant/`,
-    handleStart,
-    handleReceiveMessage,
-    handleEnd,
-    handleError,
-    messages.value,
-  );
-
-  // 清空消息
-  const handleClear = () => {
-    messages.value.splice(0); // 必须使用这种方式清空消息, 不能使用 messages.value = []，否则 ChatHelper 无法感知消息数组的变化
-  };
-
-  // 发送消息
-  const handleSend = (args: ISendData) => {
-    // 记录当前消息记录
-    const chatHistory = [...messages.value];
-    // 添加一条消息
-    messages.value.push({
-      role: 'user',
-      content: args.content,
-      cite: args.cite,
-    });
-
-    // 根据参数构造输入内容
-    const input = args.prompt
-      ? args.prompt // 如果有 prompt，直接使用
-      : args.cite
-        ? `${args.content}: ${args.cite}` // 如果有 cite，拼接 content 和 cite
-        : args.content; // 否则只使用 content
-
-    // ai 消息，id是唯一标识当前流，调用 chatHelper.stop 的时候需要传入
-    chatHelper.stream(
-      {
-        inputs: {
-          input,
-          chat_history: chatHistory,
-        },
-      },
-      1,
-    );
-  };
-
-  // 暂停聊天
-  const handleStop = () => {
-    chatHelper.stop(1);
-  };
+  }
+};
 </script>
 ```
 
-#### 非 Stream 模式
-
-##### Vue3 示例:
+### Vue 3 自定义提示词
 
 ```vue
 <template>
   <AIBlueking
-    :background="background"
-    :head-background="headBackground"
-    :loading="loading"
-    :messages="messages"
-    :position-limit="positionLimit"
-    :prompts="prompts"
-    :scroll-loading="scrollLoading"
-    :scroll-loading-end="scrollLoadingEnd"
-    :size-limit="sizeLimit"
-    :start-position="startPosition"
-    @ai-click="handleAIClick"
-    @choose-prompt="handleChoosePrompt"
-    @clear="handleClear"
-    @close="handleClose"
-    @scroll-load="handleScrollLoad"
-    @send="handleSend"
-    @stop="handleStop"
+    ref="aiBlueking"
+    :url="apiUrl"
+    :prompts="customPrompts"
   />
 </template>
-<script setup lang="ts">
-  import { type ComponentInstance, ref } from 'vue';
-
-  import AIBlueking, { type IPrompt, type IMessage, RoleType, MessageStatus } from '@blueking/ai-blueking';
 
-  import '@blueking/ai-blueking/dist/vue3/style.css';
-
-  // 展示的消息，其中 time 可以不传
-  const messages = ref<IMessage[]>([
-    {
-      content: '1+1=?',
-      time: '2023-08-12 10:28',
-      role: RoleType.User,
-    },
-    {
-      content: '1+1=3',
-      time: '2024-08-07 14:29',
-      role: RoleType.Assistant,
-      status: MessageStatus.Error,
-    },
-    {
-      content: '不对',
-      time: '2024-08-12 09:29',
-      role: RoleType.User,
-    },
-    {
-      content: '1+1=2',
-      time: '2024-08-12 09:31',
-      role: RoleType.Assistant,
-      status: MessageStatus.Loading,
-    },
-    {
-      content: '对了',
-      time: '2024-08-13 10:20',
-      role: RoleType.User,
-    },
-    {
-      content: '好的，任务已完成',
-      time: '2024-08-13 10:23',
-      role: RoleType.Assistant,
-    },
-  ]);
-  // 内置 prompt
-  const prompts = [
-    {
-      id: 1,
-      content: '帮我计算1+1的结果',
-    },
-    {
-      id: 2,
-      content: '帮我计算2+2的结果',
-    },
-  ];
-
-  // 处理ai消息的loading状态
-  const loading = ref(false);
-  // 聊天背景色
-  const background = '#f5f7fa';
-  // 头部背景色
-  const headBackground = 'linear-gradient(267deg, #2dd1f4 0%, #1482ff 95%)';
-  // 弹框位于屏幕四边的最小距离
-  const positionLimit = {
-    top: 0,
-    bottom: 0,
-    left: 0,
-    right: 0,
-  };
-  // 组件最小尺寸
-  const sizeLimit = {
-    height: 320,
-    width: 400,
-  };
-  // 初始位置
-  const startPosition = {
-    top: window.innerHeight - 560,
-    bottom: 0,
-    left: window.innerWidth - 400,
-    right: 0,
-  };
-  // 向上滚动加载
-  const scrollLoading = ref(false);
-  const scrollLoadingEnd = ref(false);
-  // 组件实例
-  const aiRef = ref<ComponentInstance<typeof AIBlueking>>();
-
-  const handleClear = () => {
-    console.log('trigger clear');
-  };
-
-  const handleSend = (val: string) => {
-    console.log('trigger send', val);
-      // args 包含:
-      // - content: 用户输入的内容
-      // - cite: 引用的内容(可选)
-      // - prompt: 使用的 prompt 模板(可选)
-  };
-
-  const handleStop = () => {
-    console.log('trigger stop');
-  };
-
-  const handleScrollLoad = () => {
-    scrollLoading.value = true;
-    setTimeout(() => {
-      // 模拟异步请求
-      messages.value.unshift(
-        ...[
-          {
-            content: '1+1=?',
-            time: '2023-08-12 9:28',
-            role: RoleType.User,
-          },
-          {
-            content: '2',
-            time: '2023-08-12 9:30',
-            role: RoleType.Assistant,
-          },
-        ],
-      );
-      // 设置状态
-      scrollLoading.value = false;
-      scrollLoadingEnd.value = true;
-    }, 1000);
-  };
-
-  const handleClose = () => {
-    console.log('trigger close');
-  };
-
-  const handleChoosePrompt = (prompt: IPrompt) => {
-    console.log('choose prompt', prompt);
-  };
-
-  const handleAIClick = (val: string) => {
-    aiRef.value?.setInputMessage(val);
-  };
+<script lang="ts" setup>
+import { ref } from 'vue';
+import AIBlueking from '@blueking/ai-blueking';
+import '@blueking/ai-blueking/dist/vue3/style.css';
+
+const aiBlueking = ref(null);
+const apiUrl = 'https://your-api-endpoint.com/assistant/';
+
+const customPrompts = [
+  '我给一段文字，概括文字的主题和主要观点，找出支持主题的关键事实、论据或观点，使用中文回答。',
+  '假设你是一名关系型数据库专家，后续的对话我会直接描述我想要的查询效果，请告诉我如何写对应的SQL查询，并解释它，如果有多个版本的SQL，以MySQL数据库为主。',
+  '你是一名经验丰富的前端开发工程师，请帮我解决以下问题...'
+];
 </script>
 ```
 
-##### Vue2 示例
-
-Vue2 下，需要安装 npm 包，里面是 vue3 资源
-
-```bash
-npm i @blueking/ai-blueking
-```
+### Vue 2 自定义提示词
 
 ```vue
 <template>
   <AIBlueking
-    :background="background"
-    :head-background="headBackground"
-    :loading="loading"
-    :messages="messages"
-    :position-limit="positionLimit"
-    :prompts="prompts"
-    :size-limit="sizeLimit"
-    :start-position="startPosition"
-    @choose-prompt="handleChoosePrompt"
-    @clear="handleClear"
-    @close="handleClose"
-    @send="handleSend"
-    @scroll="handleScroll"
-    @stop="handleStop"
+    ref="aiBlueking"
+    :url="apiUrl"
+    :prompts="customPrompts"
   />
 </template>
-<script lang="ts">
-  import { ref } from 'vue';
-
-  import AIBlueking from '@blueking/ai-blueking/vue2';
-  import '@blueking/ai-blueking/dist/vue2/style.css';
 
-  export default {
-    components: {
-      AIBlueking,
-    },
-    data() {
-      return {
-        messages: [
-          {
-            content: '你好呀',
-            role: 'assistant',
-          },
-          {
-            content: '1+1=?',
-            role: 'user',
-          },
-          {
-            content: '1+1=3',
-            role: 'assistant',
-            status: 'error',
-          },
-          {
-            content: '不对',
-            role: 'user',
-          },
-          {
-            content: '1+1=2',
-            role: 'assistant',
-            status: 'loading',
-          },
-          {
-            content: '对了',
-            role: 'user',
-          },
-          {
-            content: '好的，任务已完成',
-            role: 'assistant',
-          },
-        ],
-        prompts: [
-          {
-            id: 1,
-            content: '帮我计算1+1的结果',
-          },
-          {
-            id: 2,
-            content: '帮我计算2+2的结果',
-          },
-        ],
-        loading: false,
-        background: '#f5f7fa',
-        headBackground: 'linear-gradient(267deg, #2dd1f4 0%, #1482ff 95%)',
-        positionLimit: {
-          top: 0,
-          bottom: 0,
-          left: 0,
-          right: 0,
-        },
-        sizeLimit: {
-          height: 320,
-          width: 400,
-        },
-        startPosition: {
-          top: window.innerHeight - 560,
-          bottom: 0,
-          left: window.innerWidth - 400,
-          right: 0,
-        },
-      };
-    },
-    methods: {
-      handleClear() {
-        console.log('trigger clear');
-      },
-      handleSend(val: string) {
-        console.log('trigger send', val);
-      },
-      handleClose() {
-        console.log('trigger close');
-      },
-      handleChoosePrompt(prompt) {
-        console.log('choose prompt', prompt);
-      },
-      handleScroll(event: Event) {
-        console.log('trigger scroll', event);
-      },
-      handleStop() {
-        console.log('trigger stop');
-      },
-    },
-  };
+<script>
+import AIBlueking from '@blueking/ai-blueking/vue2';
+import '@blueking/ai-blueking/dist/vue2/style.css';
+
+export default {
+  components: {
+    AIBlueking
+  },
+  data() {
+    return {
+      apiUrl: 'https://your-api-endpoint.com/assistant/',
+      customPrompts: [
+        '我给一段文字，概括文字的主题和主要观点，找出支持主题的关键事实、论据或观点，使用中文回答。',
+        '假设你是一名关系型数据库专家，后续的对话我会直接描述我想要的查询效果，请告诉我如何写对应的SQL查询，并解释它，如果有多个版本的SQL，以MySQL数据库为主。',
+        '你是一名经验丰富的前端开发工程师，请帮我解决以下问题...'
+      ]
+    };
+  }
+};
 </script>
 ```
 
-## 开发调试
-
-### 环境准备
-
-1. 安装依赖
-
-```bash
-pnpm install
-```
-
-2. 启动开发服务器
-
-```bash
-pnpm run dev
-```
-
-3. 配置 hosts，以.woa.com 结尾的域名,以正常获取cookie
-
-```bash
-# 配置 hosts
-echo "127.0.0.1 local.dev.woa.com" >> /etc/hosts
-```
-
-### Demo 运行模式
-
-提供两种运行模式:
-
-#### 1. 静态演示模式 (Static Demo)
-
-- 无需配置环境变量
-- 展示所有功能和配置项
-- 通过 `/playground/static.vue` 查看示例
-
-#### 2. 动态演示模式 (Dynamic Demo)
-
-- 需要配置本地环境
-- 模拟真实使用场景
-- 通过 `/playground/dynamic.vue` 查看示例
+## 框架差异注意事项
 
-详细配置说明:
+### Vue 2 与 Vue 3 的区别
 
-##### 环境要求
+1. **引入方式不同**：
+   - Vue 3: `import AIBlueking from '@blueking/ai-blueking'`
+   - Vue 2: `import AIBlueking from '@blueking/ai-blueking/vue2'`
 
-1. 配置本地 hosts
+2. **样式引入不同**：
+   - Vue 3: `import '@blueking/ai-blueking/dist/vue3/style.css'`
+   - Vue 2: `import '@blueking/ai-blueking/dist/vue2/style.css'`
 
+3. **组件实例获取**：
+   - Vue 3: 通过 ref 值获取，如 `aiBlueking.value?.handleShow()`
+   - Vue 2: 通过 $refs 获取，如 `this.$refs.aiBlueking.handleShow()`
 
-2. 设置必要的变量 （不需要手动修改，playground 中已经存在）
-
-```bash
-# 网站前缀
-BK_API_GATEWAY_NAME = '<网关名称>'
-
-# 静态资源路径
-BK_API_URL_TMPL = 'https://{api_name}.example.com'
-
-# 登录地址
-BK_LOGIN_URL = 'http://login.example.com'
-```
-
-3. 登录态获取
+4. **组件定义方式**：
+   - Vue 3: 使用 Composition API 或 Options API
+   - Vue 2: 使用 Options API
 
-- 需要在其他蓝鲸系统 SaaS 中获取登录态
-- Demo 中简化了登录相关的代码实现
-- 未登录时会自动跳转到登录页面
+## 通用注意事项
 
-##### 开发注意事项
+1. 必须设置有效的 `url` 属性，指向您的 AI 服务接口
+2. 为了获得最佳体验，建议将 AI 小鲸放在全局组件中，以便在应用的任何地方都能访问
+3. 快捷操作中的提示词模板使用 `{{ SELECTED_TEXT }}` 作为选中文本的占位符
+4. Vue 2 中导入的是 `@blueking/ai-blueking/vue2`，而非根路径
 
-1. 动态模式下的 API 调用
+## 示例项目
 
-- 所有 API 请求都会通过配置的网关进行转发
-- 需要确保网关配置正确且有访问权限
+可以参考 `packages/ai-blueking/playground/dynamic-demo.vue` 了解更多使用示例。
 
-2. 错误处理
+## 常见问题
 
-- Demo 中包含了基本的错误处理逻辑
-- 未登录状态会自动跳转到登录页面
-- 其他错误会在界面上显示错误信息
+1. **Q: AI 小鲸窗口如何调整大小？**  
+   A: 用户可以通过拖动窗口边缘或右下角来调整窗口大小。
 
-3. 查看示例代码
+2. **Q: 如何实现选中文本弹出快捷操作？**  
+   A: 这是 AI 小鲸的内置功能，设置 `enablePopup` 为 true 即可启用。
 
-- 动态演示代码位于 `/playground/dynamic.vue`
-- 包含了完整的接口调用和错误处理逻辑
+3. **Q: 在 Vue 2 项目中使用时遇到兼容性问题怎么办？**  
+   A: 确保正确导入 Vue 2 版本的组件和样式，路径分别为 `@blueking/ai-blueking/vue2` 和 `@blueking/ai-blueking/dist/vue2/style.css`。