Skip to content

# AIBlueking 浮窗模式 ​

`AIBlueking` 是 AI 小鲸的顶层组件，提供开箱即用的全局 AI 助手体验。它在 `ChatBot` 的基础上集成了浮球入口、可拖拽容器、会话管理侧栏、文本选中弹窗等完整功能。

AIDev 自动加载

组件初始化时会自动通过 `agent/info` 接口加载 Agent 配置（快捷指令、提示词、欢迎语等），无需手动传入。你只需要提供 AIDev 平台发布后的 URL。

## 适用场景 ​

- SaaS 全局 AI 助手：页面右下角展示 Nimbus 浮球，点击即可展开 AI 对话面板。
- 拖拽面板：对话面板可自由拖拽、调整大小，不影响宿主页面布局。
- 划词弹窗：用户在页面中选中文本后，弹出快捷操作菜单（如"解释"、"翻译"等）。
- 辅助工具：嵌入各类 SaaS 产品作为辅助工具，提供 AI 对话能力。

## 快速开始 ​

vue

    <template>
      <AIBlueking
        ref="aiBluekingRef"
        url="https://your-aidev-url.com/api/"
        :enable-popup="true"
        :draggable="true"
        @send-message="handleSendMessage"
      />
    </template>

    <script setup lang="ts">
    import { ref } from 'vue';
    import { AIBlueking } from '@blueking/ai-blueking';
    import '@blueking/ai-blueking/dist/vue3/style.css';
    // Vue 2 项目使用：import '@blueking/ai-blueking/dist/vue2/style.css';
    import type { AIBluekingExpose } from '@blueking/ai-blueking';

    const aiBluekingRef = ref<AIBluekingExpose>();

    const handleSendMessage = (message: string) => {
      console.log('发送:', message);
    };

    // 面板控制（show 返回 Promise，建议 await 后再读 session）
    const showPanel = async () => {
      await aiBluekingRef.value?.show();
    };
    const hidePanel = () => aiBluekingRef.value?.hide();
    const showWithSession = async (code: string) => {
      await aiBluekingRef.value?.show(code);
    };
    </script>

## 核心功能 ​

### Nimbus 浮球 ​

Nimbus 是页面右下角的浮球入口，点击后展开对话面板。可通过 `hideNimbus` 属性隐藏浮球，改为自行控制面板的显示/隐藏。

### DraggableContainer 可拖拽容器 ​

对话面板支持自由拖拽和调整大小，通过 `draggable` 属性启用。可通过 `defaultHeight`、`defaultWidth`、`defaultLeft`、`defaultTop` 设置初始位置和尺寸。

### AIHeader 会话管理头部 ​

面板顶部的 Header 区域包含：

- 会话下拉列表：快速切换历史会话
- 新建会话按钮：创建新的对话
- 会话重命名、删除等管理操作

可通过 `hideHeader` 属性隐藏 Header。

### AiSelection 文本选中弹窗 ​

当用户在页面中选中文本时，自动弹出快捷操作菜单，支持将选中文本作为上下文发送给 AI。通过 `enablePopup` 属性启用。

## AIBlueking 独有 Props ​

除了继承 `ChatBot` 的所有 Props 外，`AIBlueking` 还提供以下额外属性：

属性 | 类型 | 默认值 | 说明
--- | --- | --- | ---
`enablePopup` | `boolean` | `false` | 是否启用文本选中弹窗（AiSelection）
`draggable` | `boolean` | `true` | 是否启用面板拖拽
`hideHeader` | `boolean` | `false` | 是否隐藏顶部 Header 区域
`hideNimbus` | `boolean` | `false` | 是否隐藏 Nimbus 浮球入口
`teleportTo` | `string` | `'body'` | 面板挂载的目标 DOM 节点选择器
`defaultHeight` | `number` | `600` | 面板默认高度（px）
`defaultWidth` | `number` | `400` | 面板默认宽度（px）
`defaultLeft` | `number` | — | 面板默认左偏移（px），不传则自动计算
`defaultTop` | `number` | — | 面板默认上偏移（px），不传则自动计算
`miniPadding` | `number` | `10` | 面板最小化时距离屏幕边缘的间距（px）
`enableChatSession` | `boolean` | `true` | 是否启用会话管理功能（Header 中的会话下拉列表）

> 提示：`AIBlueking` 同样支持 `ChatBot` 的所有 Props（如 `url`、`requestOptions` 等），具体请参考 ChatBot 页面嵌入模式。

## Expose 方法 ​

通过 `ref` 获取 `AIBlueking` 实例后，可调用以下方法：

### 面板控制 ​

方法 | 类型 | 说明
--- | --- | ---
`show(sessionCode?, options?)` | `(sessionCode?: string, options?: { isTemporary?: boolean }) => Promise<void>` | 展开面板；`await` 后在 `sessionList` 就绪（且默认会完成最近会话初始化）后再 resolve。详见 编程式控制
`hide()` | `() => void` | 收起面板
`handleShow(sessionCode?)` | `(sessionCode?: string) => Promise<void>` | 展开面板（内部方法）
`handleClose()` | `() => void` | 收起面板（内部方法）

### 消息操作 ​

方法 | 类型 | 说明
--- | --- | ---
`sendMessage(text)` | `(text: string) => Promise<void>` | 以编程方式发送消息
`stopGeneration()` | `() => void` | 停止当前正在生成的响应
`setCiteText(text)` | `(text: string) => void` | 设置引用文本到输入框
`focusInput()` | `() => void` | 聚焦输入框

### 快捷方式操作 ​

方法 | 类型 | 说明
--- | --- | ---
`selectShortcut(shortcut, selectedText?)` | `(shortcut: IShortcut, selectedText?: string) => void` | 选择快捷指令并显示表单，不会自动提交
`sendShortcut(shortcut, selectedText?)` | `(shortcut: IShortcut, selectedText?: string) => Promise<void>` | 直接发送快捷指令（跳过表单）

### 会话管理 ​

方法 | 类型 | 说明
--- | --- | ---
`addNewSession(options?)` | `(options?: CreateSessionOptions) => Promise<void>` | 创建新会话并自动切换
`switchToSession(code)` | `(code: string) => Promise<void>` | 切换到指定会话
`updateSessionName(code, name)` | `(sessionCode: string, newName: string) => Promise<void>` | 更新指定会话的名称

### 容器控制 ​

方法 | 类型 | 说明
--- | --- | ---
`updatePosition(x, y)` | `(x: number, y: number) => void` | 更新面板位置
`updateSize(w, h)` | `(w: number, h: number) => void` | 更新面板尺寸
`updatePositionAndSize(x, y, w, h)` | `(x: number, y: number, w: number, h: number) => void` | 同时更新位置和尺寸

### 其他 ​

方法 | 类型 | 说明
--- | --- | ---
`getChatHelper()` | `() => IChatHelper | null` | 获取内部 chatHelper 实例

## 内部结构 ​

`AIBlueking` 本质上是一个组装层，内部由以下子组件构成：

`AIBlueking` 内部创建并持有 `chatHelper` 实例，以集成模式将其传递给 `ChatBot`，确保所有子组件共享同一对话状态。各子组件通过 Manager 模式协调工作：

- Nimbus 点击 → 调用 `show()` → `DraggableContainer` 展开
- AIHeader 操作 → 通过 `SessionBusinessManager` 管理会话
- AiSelection 选中文本 → 调用 `setCiteText()` → `ChatBot` 输入框填充引用
- ChatBot 承担所有核心聊天逻辑