@blueking/ai-blueking 0.3.17 → 0.3.19

package/README.md

@@ -1,35 +1,56 @@
 # AI 小鲸使用指南
 
+## 目录
 
-## 新特性
+- [简介](#简介)
+- [安装](#安装)
+- [特性](#特性)
+- [使用指南](#使用指南)
+- [开发调试](#开发调试)
+
+## 简介
+
+AI 小鲸是一个智能对话组件,支持 Vue2/Vue3 框架,提供了丰富的交互功能和灵活的配置选项。
+
+## 安装
+
+```bash
+npm i @blueking/ai-blueking
+```
+
+## 特性
 
 - 支持 popup 弹框唤起
-- 支持引用提问功能
-- 支持快捷提问（当前支持翻译、解释功能）
-- 支持使用 `enablePopup` （若不设置，默认为ture，支持弹窗）属性来控制是否启用弹框唤起
+- 支持引用提问功能 
+- 支持快捷提问(当前支持翻译、解释功能)
+- 支持使用 `enablePopup` 属性控制弹框唤起(默认为 true)
+
+## 使用指南
+
+### 基础配置
 
-## 0.3.0 重大变更（Breaking Changes）
+#### 组件显示/隐藏控制
 
-### 1. 组件显示/隐藏方式变更
+**注意：0.3.0 版本重大变更**
 
-- 不再使用 `v-if` 控制组件显示
-- 需要定义一个变量并使用 `v-model:is-show` 绑定到组件
+- 使用 `v-model:is-show` 绑定变量控制组件显示状态
+- **不再使用 `v-if` 进行控制**
 
-### 2. handleSend 回调参数变更
+#### 消息发送回调
 
-回调函数现在接收一个对象参数，而不是简单的字符串。参数格式如下：
+**注意：0.3.0 版本重大变更**
+
+`handleSend _callback`函数现在接收一个对象参数:
 
 ```typescript
 interface ISendData {
   content: string;  // 用户输入的内容
-  cite?: string;    // 引用的内容（可选）
-  prompt?: string;  // 使用的 prompt 模板（可选）
+  cite?: string;    // 引用的内容(可选)
+  prompt?: string;  // 使用的 prompt 模板(可选)
 }
 ```
 
-## 使用示例
-
-以下展示了如何处理新的 handleSend 回调：
+以下展示了如何处理新的 handleSend 回调，完整示例请参考 [Stream 模式](#stream-模式-vue3)
 
 ```typescript
 const handleSend = (args: ISendData) => {
@@ -64,28 +85,13 @@ const handleSend = (args: ISendData) => {
 };
 ```
 
-## 注意事项
-
-- 使用 `v-model:is-show` 时需要提前定义对应的响应式变量
-- 处理 handleSend 回调时需要注意新的参数格式
-- 在调用 `chatHelper.stop` 方法时需要传入正确的流 ID
-
-
+### 模板渲染
 
+#### 知识库列表渲染
 
-## 安装
-
-```bash
-npm i @blueking/ai-blueking
-```
+可使用特定模板渲染匹配的知识库列表,示例:
 
-## 通过模板字符串渲染特定 html
-
-#### 渲染知识库列表的模板
-
-可以使用类似如下的模板来渲染匹配的知识库列表
-
-```
+```html
 <section class="knowledge-tips">
   <i class="ai-blueking-icon ai-blueking-angle-up"></i>
   <span class="knowledge-summary">
@@ -96,29 +102,43 @@ npm i @blueking/ai-blueking
     1. vivo 容器平台如何实现资源超卖方案
     <i class="ai-blueking-icon ai-blueking-cc-jump-link"></i>
   </a>
-  <a href="xxx" target="_blank" class="knowledge-link">
-    1. vivo 容器平台如何实现资源超卖方案
-    <i class="ai-blueking-icon ai-blueking-cc-jump-link"></i>
-  </a>
-  <a href="xxx" target="_blank" class="knowledge-link">
-    1. vivo 容器平台如何实现资源超卖方案
-    <i class="ai-blueking-icon ai-blueking-cc-jump-link"></i>
-  </a>
 </section>
 ```
 
-#### 渲染带有点击交互的html
+#### 交互元素渲染
 
-可以使用类似如下的模板来渲染可点击交互的 html（具有'ai-clickable'的class），点击以后会触发组件的`ai-click`事件，并把 html 标签的`data-ai`的数据传递出来。这样业务可以进行二次处理。比如说把`data-ai`上的字符串赋值到输入框，可以使用`aiRef.value?.setInputMessage(val)`来设置输入框内容。
+AI 小鲸支持渲染可点击的交互式 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-clickable` 类的 HTML 元素来创建可交互的组件。点击这些元素时，会触发组件的 `ai-click` 事件，并将 `data-ai` 属性的数据传递给事件处理程序。
+
+- **示例**：
+
+  ```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); 
+  }
+  ```
+
+这样，业务逻辑可以根据传递的数据进行二次处理，比如将 `data-ai` 上的字符串值设置到输入框中。
 
-## stream 模式
+### 使用示例
 
-不同框架，组件引入方式不同，具体可参考下面的的例子。这里使用 vue3 项目为例，来展示 stream 模式交互：
+#### Stream 模式 (Vue3)
+
+不同框架，组件引入方式不同，具体可参考下面的的例子。这里使用 vue3 项目为例，来展示 stream 模式交互
+
+参考完整示例代码:
 
 ```vue
 <template>
@@ -252,7 +272,9 @@ npm i @blueking/ai-blueking
 </script>
 ```
 
-## vue3 项目内使用（非 stream 模式）
+#### 非 Stream 模式
+
+##### Vue3 示例:
 
 ```vue
 <template>
@@ -415,15 +437,12 @@ npm i @blueking/ai-blueking
 </script>
 ```
 
-## vue2 项目内使用（非 stream 模式）
+##### Vue2 示例
 
-vue2 下，需要安装 npm 包，里面是 vue3 资源
+Vue2 下，需要安装 npm 包，里面是 vue3 资源
 
 ```bash
 npm i @blueking/bkui-library
-```
-
-```vue
 <template>
   <AIBlueking
     :background="background"
@@ -540,3 +559,79 @@ npm i @blueking/bkui-library
   };
 </script>
 ```
+
+## 开发调试
+
+### 环境准备
+
+1. 安装依赖
+
+```bash
+npm install
+```
+
+2. 启动开发服务器
+
+```bash
+npm run dev
+```
+
+### Demo 运行模式
+
+提供两种运行模式:
+
+#### 1. 静态演示模式 (Static Demo)
+
+- 无需配置环境变量
+- 展示所有功能和配置项
+- 通过 `/playground/static.vue` 查看示例
+
+#### 2. 动态演示模式 (Dynamic Demo)
+
+- 需要配置本地环境
+- 模拟真实使用场景
+- 通过 `/playground/dynamic.vue` 查看示例
+
+详细配置说明:
+
+##### 环境要求
+
+1. 配置本地 hosts
+
+
+2. 设置必要的变量
+
+```bash
+# 网站前缀
+BK_API_GATEWAY_NAME = '<网关名称>'
+
+# 静态资源路径
+BK_API_URL_TMPL = 'https://{api_name}.example.com'
+
+# 登录地址
+BK_LOGIN_URL = 'http://login.example.com'
+```
+
+3. 登录态获取
+
+- 需要在其他蓝鲸系统 SaaS 中获取登录态
+- Demo 中简化了登录相关的代码实现
+- 未登录时会自动跳转到登录页面
+
+##### 开发注意事项
+
+1. 动态模式下的 API 调用
+
+- 所有 API 请求都会通过配置的网关进行转发
+- 需要确保网关配置正确且有访问权限
+
+2. 错误处理
+
+- Demo 中包含了基本的错误处理逻辑
+- 未登录状态会自动跳转到登录页面
+- 其他错误会在界面上显示错误信息
+
+3. 查看示例代码
+
+- 动态演示代码位于 `/playground/dynamic.vue`
+- 包含了完整的接口调用和错误处理逻辑

package/dist/composables/use-popup-props.d.ts

@@ -0,0 +1,4 @@
+export declare const POPUP_INJECTION_KEY = "enablePopup";
+export declare function usePopup(): {
+    enablePopup: boolean;
+};

package/dist/composables/use-select-pop.d.ts

@@ -1,4 +1,4 @@
-export declare function useSelect(): {
+export declare function useSelect(enablePopup: boolean): {
     isIconVisible: import("vue").Ref<boolean>;
     iconPosition: import("vue").Ref<{
         top: string;