原子组件组装

当 ChatBot 或 AIBlueking 无法满足定制化需求时，可以直接使用 @blueking/chat-x 的原子 UI 与 @blueking/chat-helper 的 SDK 组装业务，获得最大的布局与交互自由度。

适用场景

需要非标准布局（左右分栏、嵌入复杂页面等）
需要替换默认输入区、消息气泡、工具栏等行为
需要将对话能力与现有状态管理深度整合

何时不应使用

原子模式需要自行完成初始化、生命周期与状态映射，复杂度高。若只需嵌入聊天窗口或完整面板，优先：

组装步骤（与 chat-helper 当前 API 对齐）

1. 创建 `AGUIProtocol` 与 `useChatHelper`

AGUIProtocol 构造函数仅接收可选回调（onStart / onMessage / onDone / onError），不要传入 baseURL。HTTP 基址放在 requestData.urlPrefix。

import { AGUIProtocol, useChatHelper } from '@blueking/chat-helper';

const protocol = new AGUIProtocol({
  onError: (err) => console.error(err),
});

const chatHelper = useChatHelper({
  requestData: {
    urlPrefix: 'https://your-api.example/api/',
    headers: () => ({ Authorization: `Bearer ${getToken()}` }),
  },
  protocol,
});

2. 注入消息模块（必须）

在首次发起流式请求前调用（建议在 onMounted 内、getAgentInfo 之前亦可）：

protocol.injectMessageModule(chatHelper.message);

AGUIProtocol 依赖 IMessageModule 将 TEXT_MESSAGE_* 等事件落到消息列表；遗漏会导致流式内容无法显示。

3. 初始化会话

await chatHelper.agent.getAgentInfo();
await chatHelper.session.getSessions();

const first = chatHelper.session.list.value[0];
if (first?.sessionCode) {
  await chatHelper.session.chooseSession(first.sessionCode);
} else {
  await chatHelper.session.createSession(
    { sessionCode: `new_${Date.now()}`, sessionName: '新会话' },
    { loadMessages: false },
  );
}

注意：会话列表字段为 session.list，切换会话为 chooseSession，不是 sessions / switchSession。

4. 连接 chat-x 组件

使用 chatHelper.message.list 作为 MessageContainer 的 messages
用 chatHelper.agent.isChatting 映射 MessageStatus / MessageToolsStatus（与 ChatBot 内部 composable 逻辑一致）
发送消息使用 chatHelper.agent.chat(content, sessionCode, ...)，由 SDK 负责创建用户消息并打开 SSE；不要与旧文档中的 message.sendMessage 混淆

MessageContainer、ChatInput 的交互以 props 回调 为准（如 onAgentAction、onSendMessage），不是早期示例里的 @cite / @send 等自定义事件。

5. 卸载清理

import { onBeforeUnmount } from 'vue';

onBeforeUnmount(() => {
  const code = chatHelper.session.current.value?.sessionCode;
  chatHelper.agent.abortChat();
  if (code) void chatHelper.agent.stopChat(code);
});

当前 AGUIProtocol 没有 destroy() 方法；以中止请求 + 可选 stopChat 为主。

可运行示例与 Mock

原子组件组装示例内嵌演示不模拟小鲸初始化接口，仅 Mock session_content + chat_completion（AG-UI SSE），用于验证流式解析与 chat-x 渲染；真实 urlPrefix 请对接网关（如 BK_API_GATEWAY_NAME 等环境变量）。

原子组件组装 ​

适用场景 ​

何时不应使用 ​

组装步骤（与 chat-helper 当前 API 对齐） ​

1. 创建 AGUIProtocol 与 useChatHelper ​

2. 注入消息模块（必须） ​

3. 初始化会话 ​

4. 连接 chat-x 组件 ​

5. 卸载清理 ​

可运行示例与 Mock ​

延伸阅读 ​