ChatBot 组件

ChatBot 是 AI 小鲸的核心聊天组件，提供输入框、消息列表、快捷指令等完整的聊天交互能力。它支持独立模式和集成模式两种使用方式。

非 Vue 宿主

宿主无 Vue 时，请使用 v2.1.4-beta.8+ 的 mountChatBot（@blueking/ai-blueking/standalone），见 Standalone 集成指南。

基本用法

<template>
  <!-- 独立模式：只需传入 url -->
  <ChatBot url="/api/ai" :shortcuts="shortcuts" />
</template>

<script setup>
import { ChatBot } from '@blueking/ai-blueking';
</script>

<template>
  <!-- 集成模式：传入外部 chatHelper -->
  <ChatBot :chat-helper="chatHelper" />
</template>

<script setup>
import { ChatBot } from '@blueking/ai-blueking';
import { useChatHelper } from '@blueking/chat-helper';

const chatHelper = useChatHelper({ requestData: { urlPrefix: '/api/ai' } });
</script>

Props

基础配置

属性	类型	默认值	说明
url	string	''	API 地址（独立模式必填）
chatHelper	IChatHelper	—	外部 chatHelper（集成模式传入，与 url 二选一）
requestOptions	MaybeRefOrGetter<IRequestOptions>	—	请求配置（仅独立模式；headers / data 支持对象、函数、ref、computed）

会话配置

属性	类型	默认值	说明
autoLoad	boolean	true	是否自动加载最近会话
sessionCode	string	—	指定初始会话编码

快捷方式与资源

属性	类型	默认值	说明
shortcuts	IShortcut[]	[]	快捷指令列表
resources	IAiSlashMenuItem[]	[]	资源列表（@ 触发）
prompts	string[]	—	预设提示词（/ 触发）

界面配置

属性	类型	默认值	说明
helloText	string	—	欢迎语
placeholder	string	—	输入框占位符
renderMode	RenderMode	'chat'	渲染模式：chat（默认）、share（分享）、test（测试）
height	string | number	—	容器高度
maxWidth	string | number	—	最大宽度
extCls	string	—	额外 CSS 类名
placement	'left' | 'right'	'left'	执行情况侧面板位置

分享与选择

属性	类型	默认值	说明
enableSelection	boolean	false	是否启用多选模式（分享用）
shareLoading	boolean	false	分享加载状态

高级配置

属性	类型	默认值	说明
messageToolsTippyOptions	MessageToolsTippyOptions	—	消息工具栏 Tippy 配置（如 appendTo，用于控制弹窗挂载位置和层级）
resizeProps	{ disabled?, initialDivide?, max?, min? }	—	ResizeLayout 配置（执行情况侧面板拖拽）

侧栏自定义渲染

透传 ChatContainer 侧栏能力，用于 FlowAgent 节点详情等自定义 Tab。用法见 侧栏 Tab 自定义渲染。

属性	类型	默认值	说明
getSideRenderComponent	GetSideRenderComponent	—	(h, props) => VNode | undefined。返回 VNode 时作为侧栏内容根；返回 undefined 时使用 addCustomTab 的 data.component
getSideTabRenderComponent	GetSideTabRenderComponent	—	(h, tab, { removeCustomTab }) => VNode | undefined。自定义 Tab 标签；未返回时使用默认图标 + 文案 + 关闭按钮
onCustomTabChange	OnCustomTabChange	—	(tab) => Promise<unknown>。Tab 切换时拉取详情并写入 data.props；未传且为 Flow 节点 Tab（含 task_id、node_id）时，使用内置 getFlowAgentTaskNodeInfo

Events

消息事件

事件名	参数	说明
send-message	(message: string)	用户发送消息
receive-start	—	流式响应开始（仅独立模式）
receive-text	—	流式接收文本（仅独立模式）
receive-end	—	流式响应结束（仅独立模式）
stop	—	用户停止生成
error	(error: Error)	发生错误
feedback	(tool, message, reasonList, otherReason)	反馈提交成功

会话事件

事件名	参数	说明
session-switched	(session: ISession | null)	会话切换完成
agent-info-loaded	(chatHelper: IChatHelper)	Agent 信息加载完成（仅独立模式）

快捷方式事件

事件名	参数	说明
shortcut-click	({ shortcut, source })	快捷指令点击

分享事件

事件名	参数	说明
confirm-share	(messages: Message[])	确认分享
cancel-share	—	取消分享
request-share	—	请求进入分享模式

执行情况事件

事件名	参数	说明
execution-panel-change	(isCollapse: boolean)	执行情况面板展开/折叠

Expose 方法

消息操作

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

快捷方式操作

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

会话操作

方法	类型	说明
switchSession	(sessionCode: string) => Promise<void>	切换到指定会话

分享操作

方法	类型	说明
enterShareMode	() => void	进入分享选择模式
exitShareMode	() => void	退出分享选择模式

其他

方法/属性	类型	说明
getChatHelper	() => IChatHelper | null	获取内部 chatHelper 实例
messages	ComputedRef<Message[]>	当前消息列表（只读）
currentSession	Ref<ISession | null>	当前会话（响应式）
isGenerating	Ref<boolean>	是否正在生成（响应式）

使用 Expose

<template>
  <ChatBot ref="chatbotRef" url="/api/ai" />
  <button @click="chatbotRef?.sendMessage('你好')">发送</button>
</template>

<script setup>
import { ref } from 'vue';
import { ChatBot } from '@blueking/ai-blueking';

const chatbotRef = ref<InstanceType<typeof ChatBot>>();
</script>

两种模式对比

特性	独立模式	集成模式
初始化方式	传入 url，组件内部创建 chatHelper	传入外部 chatHelper 实例
适用场景	快速接入，无需外部状态管理	需要与外部逻辑共享数据/状态
流式事件	✅ 触发 receive-start/text/end	❌ 由外部 chatHelper 自行处理
requestOptions	✅ 生效	❌ 不生效（由外部配置）
Agent 信息加载	自动加载，触发 agent-info-loaded	由外部控制
数据控制权	组件内部管理	外部完全控制

独立模式示例

<template>
  <ChatBot
    url="/api/ai"
    :shortcuts="shortcuts"
    :request-options="requestOptions"
    hello-text="你好，我是 AI 小鲸！"
    placeholder="输入你的问题..."
    @send-message="onSend"
    @receive-end="onReceiveEnd"
  />
</template>

<script setup>
import { ChatBot } from '@blueking/ai-blueking';

const shortcuts = [
  { id: 'explain', name: '解释代码', icon: 'code', description: '解释选中的代码' },
];

const requestOptions = {
  headers: { 'X-Custom-Header': 'value' },
  data: { extra: 'params' },
};

function onSend(message) {
  console.log('用户发送:', message);
}

function onReceiveEnd() {
  console.log('回复完成');
}
</script>

集成模式示例

<template>
  <ChatBot :chat-helper="chatHelper" :shortcuts="shortcuts" />
</template>

<script setup>
import { ChatBot } from '@blueking/ai-blueking';
import { useChatHelper } from '@blueking/chat-helper';

const chatHelper = useChatHelper({
  requestData: {
    urlPrefix: '/api/ai',
    headers: { Authorization: 'Bearer xxx' },
  },
});

// 外部可以直接操作 chatHelper
chatHelper.agent.getAgentInfo();
</script>