pnpm add @blueking/chat-helper

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

const chatHelper = useChatHelper({
  requestData: {
    urlPrefix: 'https://your-api.com/api/',
    headers: () => ({
      Authorization: `Bearer ${getToken()}`,
    }),
    data: () => ({
      app_id: 'your-app-id',
    }),
  },
  protocol: new AGUIProtocol({
    onStart: () => console.log('开始响应'),
    onDone: () => console.log('响应完成'),
    onError: (error) => console.error('错误:', error),
  }),
});

// 解构模块
const { agent, session, message, http } = chatHelper;

用户操作 → Agent/Session/Message → Mediator → HTTP → 后端 API
                    ↑                                      ↓
                    ←────────── 流式事件/响应数据 ←─────────

// 响应式数据
agent.info              // Ref<IAgentInfo | null>
agent.isInfoLoading     // Ref<boolean>
agent.isChatting        // Ref<boolean>

// 方法
agent.getAgentInfo()                              // 获取 Agent 信息
agent.chat(userInput, sessionCode, url?, config?) // 发送消息
agent.stopChat()                                  // 停止聊天
agent.resumeStreamingChat(sessionCode)            // 恢复流式聊天

// 响应式数据
session.list           // Ref<ISession[]>
session.current        // Ref<ISession | null>
session.isListLoading  // Ref<boolean>

// 方法
session.getSessions()                  // 获取会话列表
session.chooseSession(sessionCode)     // 选择会话（自动加载消息）
session.createSession(session)         // 创建会话
session.updateSession(session)         // 更新会话
session.deleteSession(sessionCode)     // 删除会话
session.renameSession(sessionCode)     // AI 重命名会话
session.postSessionFeedback(feedback)  // 提交会话反馈

// 响应式数据
message.list           // Ref<IMessage[]>
message.isListLoading  // Ref<boolean>
message.isDeleteLoading // Ref<boolean>

// 方法
message.getMessages(sessionCode)         // 获取消息列表
message.plusMessage(message)             // 添加消息（本地）
message.createAndPlusMessage(message)    // 创建并添加消息（调用接口）
message.modifyMessage(message)           // 修改消息（本地）
message.deleteMessages(messages)         // 批量删除消息
message.getCurrentLoadingMessage()       // 获取当前加载中的消息
message.getMessageByMessageId(id)        // 根据 ID 获取消息

<template>
  <div class="chat-app">
    <!-- 消息容器 -->
    <MessageContainer
      :messages="message.list.value"
      :message-status="messageStatus"
      :on-agent-action="handleAgentAction"
      @stop-streaming="handleStop"
    />
    
    <!-- 输入框 -->
    <ChatInput
      v-model="userInput"
      :message-status="messageStatus"
      :shortcuts="shortcuts"
      :on-send-message="handleSend"
      :on-stop-sending="handleStop"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, computed, onMounted, onUnmounted } from 'vue';
import { ChatInput, MessageContainer, MessageStatus } from '@blueking/chat-x';
import { useChatHelper, AGUIProtocol } from '@blueking/chat-helper';

const userInput = ref('');
const isStreaming = ref(false);

// 创建 chatHelper 实例
const chatHelper = useChatHelper({
  requestData: {
    urlPrefix: '/api/',
    headers: () => ({ Authorization: `Bearer ${getToken()}` }),
  },
  protocol: new AGUIProtocol({
    onStart: () => { isStreaming.value = true; },
    onDone: () => { isStreaming.value = false; },
    onError: () => { isStreaming.value = false; },
  }),
});

const { agent, session, message } = chatHelper;

// 消息状态映射
const messageStatus = computed(() => 
  isStreaming.value ? MessageStatus.Streaming : MessageStatus.Complete
);

// 初始化
onMounted(async () => {
  await agent.getAgentInfo();
  await session.getSessions();
  if (session.list.value.length > 0) {
    await session.chooseSession(session.list.value[0].sessionCode);
  }
});

// 清理
onUnmounted(() => {
  agent.stopChat();
});

// 发送消息
const handleSend = async (value: string) => {
  if (!session.current.value?.sessionCode) return;
  userInput.value = '';
  await agent.chat(value, session.current.value.sessionCode);
};

// 停止
const handleStop = () => {
  agent.stopChat();
};

// AI 消息操作
const handleAgentAction = async (tool) => {
  if (tool.id === 'like') return ['回答准确', '信息全面'];
  if (tool.id === 'unlike') return ['信息错误', '回答不相关'];
};
</script>

const protocol = new AGUIProtocol({
  onStart: () => { /* 流式开始 */ },
  onMessage: (event) => { /* 每个事件 */ },
  onDone: () => { /* 流式完成 */ },
  onError: (error) => { /* 发生错误 */ },
});

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

class CustomProtocol extends AGUIProtocol {
  // 重写文本消息处理
  handleTextMessageChunkEvent(event: ITextMessageChunkEvent) {
    // 自定义逻辑（如敏感词过滤）
    console.log('接收文本:', event.delta);
    super.handleTextMessageChunkEvent(event);
  }
  
  // 重写思考开始
  handleThinkingStartEvent(event) {
    showThinkingAnimation();
    super.handleThinkingStartEvent(event);
  }
}

useChatHelper({
  requestData: {
    urlPrefix: '/api/',
    // 动态 headers
    headers: () => ({
      Authorization: `Bearer ${localStorage.getItem('token')}`,
      'X-Request-ID': crypto.randomUUID(),
    }),
    // 动态 data
    data: () => ({
      app_id: getCurrentAppId(),
      tenant_id: getTenantId(),
    }),
  },
});

useChatHelper({
  requestData: { urlPrefix: '/api/' },
  interceptors: {
    request: (config) => {
      console.log('Request:', config.url);
      return config;
    },
    response: (response) => {
      if (response.data.code !== 0) {
        showError(response.data.message);
      }
      return response;
    },
  },
});

// 带额外参数发送
agent.chat(userInput, sessionCode, 'custom_chat/', {
  data: {
    temperature: 0.7,
    max_tokens: 2000,
    model: 'gpt-4',
  },
  headers: {
    'X-Chat-Mode': 'creative',
  },
});

enum MessageRole {
  User = 'user',           // 用户消息
  Assistant = 'assistant', // AI 助手
  Reasoning = 'reasoning', // 推理过程
  Tool = 'tool',           // 工具调用结果
  Activity = 'activity',   // 活动（如引用文档）
  System = 'system',       // 系统消息
  Info = 'info',           // 信息提示
  // ... 更多角色
}

enum MessageStatus {
  Pending = 'pending',     // 等待中
  Streaming = 'streaming', // 流式传输
  Complete = 'complete',   // 完成
  Error = 'error',         // 错误
  Stop = 'stop',           // 已停止
}

onUnmounted(() => {
  agent.stopChat();
});

// ✅ 推荐：自动停止聊天、加载消息
await session.chooseSession(sessionCode);

// ❌ 不推荐：手动操作
agent.stopChat();
session.current.value = ...;
message.getMessages(sessionCode);

import { MessageStatus, MessageRole } from '@blueking/chat-helper';

// ✅ 推荐
if (msg.status === MessageStatus.Streaming) { }

// ❌ 不推荐
if (msg.status === 'streaming') { }

// ✅ 推荐：不阻塞
onMessage: (event) => {
  console.log(event);
  asyncOperation(); // 不 await
}

// ❌ 不推荐：阻塞
onMessage: async (event) => {
  await someAsyncOperation(); // 阻塞
}