@blueking/chat-helper 0.0.1-beta.3 → 0.0.1-beta.30

package/README.md

@@ -2,6 +2,17 @@
 
 一个用于 Vue3 的聊天助手工具包，提供完整的 AI 对话功能，支持流式响应、会话管理、消息管理等功能。
 
+## 特性
+
+- 🚀 **Vue3 Composition API**：基于 Vue3 的响应式系统，提供流畅的开发体验
+- 💬 **完整的会话管理**：支持多会话创建、切换、更新和删除
+- 📨 **消息管理**：支持消息列表、添加、修改、删除和批量操作
+- 🤖 **AI Agent 集成**：轻松接入 AI 代理，获取代理信息和进行对话
+- 🌊 **流式响应**：支持 SSE（Server-Sent Events）流式响应，实时展示 AI 回复
+- 🎯 **中介者模式**：模块间通过中介者协调通信，降低耦合度
+- 🔧 **高度可定制**：支持自定义拦截器、自定义 Protocol、自定义请求配置
+- 📝 **TypeScript 支持**：完整的类型定义，提供良好的类型提示
+
 ## 安装
 
 ```bash
@@ -27,6 +38,34 @@ const chatHelper = useChatHelper({
 const { agent, session, message, http } = chatHelper;
 ```
 
+## 架构设计
+
+`@blueking/chat-helper` 采用**中介者模式（Mediator Pattern）**进行架构设计，将复杂的模块间通信集中到中介者对象中，降低了各模块之间的耦合度。
+
+### 核心模块
+
+- **Agent 模块**：管理 AI 代理相关功能，包括获取代理信息、开始聊天、停止聊天等
+- **Session 模块**：管理聊天会话，包括会话列表、创建、切换、更新和删除
+- **Message 模块**：管理聊天消息，包括消息列表、添加、修改和删除
+- **HTTP 模块**：底层 HTTP 请求封装，提供各种 API 调用方法和 SSE 流式响应支持
+- **Mediator 模块**：中介者，协调各模块之间的通信，避免模块间直接依赖
+
+### 数据流向
+
+```
+用户操作 → Agent/Session/Message 模块 → Mediator → HTTP 模块 → 后端 API
+                    ↑                                            ↓
+                    ←────────── 响应数据/流式事件 ←─────────────
+```
+
+### Protocol 系统
+
+`@blueking/chat-helper` 提供了可扩展的 Protocol 系统来处理 SSE 流式响应：
+
+- **ISSEProtocol 接口**：定义了流式响应的处理接口
+- **AGUIProtocol 实现**：默认的 AGUI 协议实现，支持丰富的事件类型
+- **自定义 Protocol**：用户可以实现自己的 Protocol 来处理特定的流式响应格式
+
 ## useChatHelper 返回数据说明
 
 `useChatHelper` 返回一个包含四个模块的对象：
@@ -44,10 +83,17 @@ agent.isInfoLoading; // Ref<boolean> - agent 信息加载状态
 
 // 方法
 agent.getAgentInfo(); // () => Promise<void> - 获取 agent 信息
-agent.chat(); // () => void - 开始聊天（流式响应）
+agent.chat(userInput, sessionCode, url?, config?); // (userInput: string, sessionCode: string, url?: string, config?: IRequestConfig) => Promise<void> - 开始聊天（流式响应）
 agent.stopChat(); // () => Promise<void> - 停止聊天
 ```
 
+**参数说明**：
+
+- `userInput`: 用户输入的消息内容，必需参数
+- `sessionCode`: 会话代码，必需参数，标识当前聊天会话
+- `url`: 可选参数，自定义聊天接口地址，默认为 `'chat_completion/'`
+- `config`: 可选参数，额外的请求配置（如自定义 headers、data 等）
+
 **使用示例**：
 
 ```vue
@@ -55,32 +101,66 @@ agent.stopChat(); // () => Promise<void> - 停止聊天
   <div>
     <div v-if="agent.isInfoLoading">加载中...</div>
     <div v-else-if="agent.info">
-      <h2>{{ agent.info.name }}</h2>
-      <p>{{ agent.info.description }}</p>
+      <h2>{{ agent.info.agentName }}</h2>
+      <p>{{ agent.info.conversationSettings?.openingRemark }}</p>
     </div>
+    <input
+      v-model="userInput"
+      placeholder="请输入消息..."
+    />
     <button @click="startChat">开始对话</button>
     <button @click="agent.stopChat">停止对话</button>
   </div>
 </template>
 
 <script setup lang="ts">
-  import { onMounted } from 'vue';
+  import { onMounted, ref } from 'vue';
   import { useChatHelper } from '@blueking/chat-helper';
 
-  const { agent } = useChatHelper({
+  const { agent, session } = useChatHelper({
     /* ... */
   });
 
+  const userInput = ref('');
+
   onMounted(() => {
     agent.getAgentInfo();
   });
 
   const startChat = () => {
-    agent.chat();
+    if (session.current?.sessionCode && userInput.value.trim()) {
+      agent.chat(userInput.value, session.current.sessionCode);
+      userInput.value = ''; // 清空输入框
+    }
   };
 </script>
 ```
 
+**高级用法 - 自定义请求配置**：
+
+```typescript
+// 使用自定义 URL
+agent.chat('你好', sessionCode, 'custom_chat_endpoint/');
+
+// 使用自定义请求配置
+agent.chat('你好', sessionCode, undefined, {
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+  data: {
+    temperature: 0.7,
+    max_tokens: 1000,
+  },
+});
+
+// 同时使用自定义 URL 和配置
+agent.chat('你好', sessionCode, 'custom_chat_endpoint/', {
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+});
+```
+
 ### 2. session - 会话模块
 
 管理聊天会话的创建、切换、更新和删除。
@@ -118,7 +198,7 @@ session.deleteSession(sessionCode); // (sessionCode: string) => Promise<void> -
         @click="session.chooseSession(item.sessionCode)"
         :class="{ active: session.current?.sessionCode === item.sessionCode }"
       >
-        {{ item.title }}
+        {{ item.sessionName }}
       </li>
     </ul>
     <button @click="createNewSession">新建会话</button>
@@ -139,7 +219,8 @@ session.deleteSession(sessionCode); // (sessionCode: string) => Promise<void> -
 
   const createNewSession = () => {
     session.createSession({
-      title: '新会话',
+      sessionName: '新会话',
+      sessionCode: `session_${Date.now()}`,
       // ... 其他会话属性
     });
   };
@@ -157,17 +238,28 @@ const { message } = chatHelper;
 message.list; // Ref<IMessage[]> - 消息列表
 message.isListLoading; // Ref<boolean> - 列表加载状态
 message.isDeleteLoading; // Ref<boolean> - 删除加载状态
+message.isBatchDeleteLoading; // Ref<boolean> - 批量删除加载状态
 
 // 方法
 message.getMessages(sessionCode); // (sessionCode: string) => Promise<void> - 获取消息列表
-message.plusMessage(message); // (message: IMessage) => void - 添加消息
+message.plusMessage(message); // (message: IMessage) => Promise<void> - 添加消息
 message.modifyMessage(message); // (message: IMessage) => void - 修改消息
-message.deleteMessage(id); // (id: number) => Promise<void> - 删除消息
-message.batchDeleteMessages(ids); // (ids: number[]) => Promise<void> - 批量删除消息
+message.deleteMessage(id); // (id: string) => Promise<void> - 删除消息
+message.batchDeleteMessages(ids); // (ids: string[]) => Promise<void> - 批量删除消息
 message.getCurrentLoadingMessage(); // () => IMessage | undefined - 获取当前加载中的消息
-message.getMessageById(id); // (id: number) => IMessage | undefined - 根据 ID 获取消息
+message.getMessageByMessageId(id); // (id: string) => IMessage | undefined - 根据消息 ID 获取消息
 ```
 
+**方法说明**：
+
+- `getMessages`: 获取指定会话的所有消息列表
+- `plusMessage`: 主动添加一条新消息到列表（会先调用后端接口创建消息，然后添加到列表最前面）
+- `modifyMessage`: 修改已存在的消息（本地更新，不调用接口）
+- `deleteMessage`: 删除单条消息（调用接口删除并从列表中移除）
+- `batchDeleteMessages`: 批量删除多条消息（调用接口批量删除并从列表中移除）
+- `getCurrentLoadingMessage`: 获取当前正在加载/流式传输中的 AI 响应消息（状态为 Pending 或 Streaming）
+- `getMessageByMessageId`: 根据消息 ID 从列表中查找消息
+
 **使用示例**：
 
 ```vue
@@ -175,31 +267,45 @@ message.getMessageById(id); // (id: number) => IMessage | undefined - 根据 ID
   <div class="message-list">
     <div
       v-for="msg in message.list"
-      :key="msg.id"
+      :key="msg.messageId"
       class="message-item"
     >
       <div class="role">{{ msg.role }}</div>
       <div class="content">
-        <div
-          v-for="(content, index) in msg.content"
-          :key="index"
-        >
-          <template v-if="content.type === 'text'">
-            {{ content.data }}
-          </template>
+        <!-- 根据消息类型显示不同内容 -->
+        <div v-if="msg.role === 'user'">
+          {{ typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content) }}
+        </div>
+        <div v-else-if="msg.role === 'assistant'">
+          {{ msg.content || '' }}
         </div>
       </div>
-      <button @click="message.deleteMessage(msg.id)">删除</button>
+      <button @click="message.deleteMessage(msg.messageId)">删除</button>
     </div>
+    <button
+      @click="batchDelete"
+      :disabled="message.isBatchDeleteLoading"
+    >
+      批量删除选中消息
+    </button>
   </div>
 </template>
 
 <script setup lang="ts">
+  import { ref } from 'vue';
   import { useChatHelper } from '@blueking/chat-helper';
 
   const { message } = useChatHelper({
     /* ... */
   });
+
+  const selectedIds = ref<string[]>([]);
+
+  const batchDelete = () => {
+    if (selectedIds.value.length > 0) {
+      message.batchDeleteMessages(selectedIds.value);
+    }
+  };
 </script>
 ```
 
@@ -283,7 +389,7 @@ useChatHelper({
     // 响应拦截器
     response: response => {
       // 对响应数据做些什么
-      console.log('Response:', response);
+      console.log('IResponse:', response);
 
       // 可以在这里做统一的错误处理
       if (response.data.code !== 0) {
@@ -681,6 +787,223 @@ class SafeProtocol extends AGUIProtocol {
 
 </details>
 
+## 实战场景
+
+### 场景 1：带输入框的聊天界面
+
+使用独立的 `ref` 管理用户输入：
+
+```vue
+<template>
+  <div class="chat-interface">
+    <div class="messages">
+      <div
+        v-for="msg in message.list"
+        :key="msg.id"
+      >
+        <!-- 消息渲染 -->
+      </div>
+    </div>
+    <div class="input-box">
+      <textarea
+        v-model="userInput"
+        @keydown.enter.prevent="handleSend"
+        placeholder="输入消息，按 Enter 发送..."
+        :disabled="isStreaming"
+      />
+      <button
+        @click="handleSend"
+        :disabled="!canSend"
+      >
+        {{ isStreaming ? '发送中...' : '发送' }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { computed, ref } from 'vue';
+  import { useChatHelper } from '@blueking/chat-helper';
+
+  const { agent, message, session } = useChatHelper({
+    /* ... */
+  });
+  const isStreaming = ref(false);
+  const userInput = ref('');
+
+  const canSend = computed(
+    () => !isStreaming.value && userInput.value.trim().length > 0 && session.current?.sessionCode,
+  );
+
+  const handleSend = () => {
+    if (canSend.value) {
+      isStreaming.value = true;
+      const input = userInput.value;
+      userInput.value = ''; // 立即清空输入框
+      agent.chat(input, session.current!.sessionCode).finally(() => {
+        isStreaming.value = false;
+      });
+    }
+  };
+</script>
+```
+
+### 场景 2：消息批量管理
+
+实现消息的选择和批量删除功能：
+
+```vue
+<template>
+  <div class="message-manager">
+    <div class="toolbar">
+      <button @click="selectAll">全选</button>
+      <button @click="clearSelection">取消选择</button>
+      <button
+        @click="batchDelete"
+        :disabled="selectedIds.length === 0 || message.isBatchDeleteLoading"
+      >
+        {{ message.isBatchDeleteLoading ? '删除中...' : `删除选中 (${selectedIds.length})` }}
+      </button>
+    </div>
+
+    <div class="messages">
+      <div
+        v-for="msg in message.list"
+        :key="msg.messageId"
+        @click="toggleSelection(msg.messageId)"
+        :class="{ selected: selectedIds.includes(msg.messageId) }"
+      >
+        <input
+          type="checkbox"
+          :checked="selectedIds.includes(msg.messageId)"
+          @click.stop
+        />
+        <!-- 消息内容 -->
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useChatHelper } from '@blueking/chat-helper';
+
+  const { message } = useChatHelper({
+    /* ... */
+  });
+  const selectedIds = ref<string[]>([]);
+
+  const toggleSelection = (id: string) => {
+    const index = selectedIds.value.indexOf(id);
+    if (index > -1) {
+      selectedIds.value.splice(index, 1);
+    } else {
+      selectedIds.value.push(id);
+    }
+  };
+
+  const selectAll = () => {
+    selectedIds.value = message.list.value.filter(msg => msg.messageId).map(msg => msg.messageId!);
+  };
+
+  const clearSelection = () => {
+    selectedIds.value = [];
+  };
+
+  const batchDelete = async () => {
+    if (selectedIds.value.length > 0) {
+      await message.batchDeleteMessages(selectedIds.value);
+      selectedIds.value = [];
+    }
+  };
+</script>
+```
+
+### 场景 3：自定义聊天参数
+
+根据不同场景使用不同的聊天配置：
+
+```vue
+<template>
+  <div class="custom-chat">
+    <div class="settings">
+      <label>
+        温度:
+        <input
+          v-model.number="temperature"
+          type="range"
+          min="0"
+          max="1"
+          step="0.1"
+        />
+        {{ temperature }}
+      </label>
+      <label>
+        最大tokens:
+        <input
+          v-model.number="maxTokens"
+          type="number"
+        />
+      </label>
+      <label>
+        模式:
+        <select v-model="mode">
+          <option value="default">默认</option>
+          <option value="creative">创意</option>
+          <option value="precise">精确</option>
+        </select>
+      </label>
+    </div>
+
+    <textarea
+      v-model="userInput"
+      placeholder="输入消息..."
+    />
+    <button @click="sendWithConfig">发送</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useChatHelper } from '@blueking/chat-helper';
+
+  const { agent, session } = useChatHelper({
+    /* ... */
+  });
+
+  const userInput = ref('');
+  const temperature = ref(0.7);
+  const maxTokens = ref(1000);
+  const mode = ref('default');
+
+  const sendWithConfig = () => {
+    if (!session.current?.sessionCode || !userInput.value.trim()) return;
+
+    // 根据模式设置不同的端点
+    const endpoint =
+      mode.value === 'creative'
+        ? 'chat_completion_creative/'
+        : mode.value === 'precise'
+        ? 'chat_completion_precise/'
+        : undefined;
+
+    // 自定义请求参数
+    agent.chat(userInput.value, session.current.sessionCode, endpoint, {
+      data: {
+        temperature: temperature.value,
+        max_tokens: maxTokens.value,
+        mode: mode.value,
+      },
+      headers: {
+        'X-Chat-Mode': mode.value,
+      },
+    });
+
+    userInput.value = ''; // 清空输入框
+  };
+</script>
+```
+
 ## 完整示例
 
 以下是一个完整的聊天应用示例：
@@ -698,7 +1021,7 @@ class SafeProtocol extends AGUIProtocol {
           @click="session.chooseSession(item.sessionCode)"
           :class="{ active: session.current?.sessionCode === item.sessionCode }"
         >
-          {{ item.title }}
+          {{ item.sessionName }}
           <button @click.stop="session.deleteSession(item.sessionCode)">删除</button>
         </li>
       </ul>
@@ -713,49 +1036,31 @@ class SafeProtocol extends AGUIProtocol {
       >
         <div
           v-for="msg in message.list"
-          :key="msg.id"
+          :key="msg.messageId"
           :class="['message-item', msg.role]"
         >
           <div class="message-content">
-            <template
-              v-for="(content, index) in msg.content"
-              :key="index"
-            >
-              <!-- 文本消息 -->
-              <div
-                v-if="content.type === 'text'"
-                class="text-content"
-              >
-                {{ content.data }}
-              </div>
-
-              <!-- 思考过程 -->
-              <div
-                v-else-if="content.type === 'thinking'"
-                class="thinking-content"
-              >
-                <strong>{{ content.data.title }}</strong>
-                <p>{{ content.data.text }}</p>
-              </div>
-
-              <!-- 工具调用 -->
-              <div
-                v-else-if="content.type === 'tool_call'"
-                class="tool-call-content"
-              >
-                <strong>调用工具: {{ content.data.toolCallName }}</strong>
-                <pre>{{ content.data.args }}</pre>
-              </div>
+            <template v-if="msg.role === 'user'">
+              {{ typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content) }}
+            </template>
+            <template v-else-if="msg.role === 'assistant'">
+              {{ msg.content || '' }}
             </template>
           </div>
-          <button @click="message.deleteMessage(msg.id)">删除</button>
+          <button @click="message.deleteMessage(msg.messageId)">删除</button>
         </div>
       </div>
 
       <!-- 输入区域 -->
       <div class="input-area">
+        <input
+          v-model="userInput"
+          @keyup.enter="sendMessage"
+          placeholder="输入消息..."
+          :disabled="isStreaming"
+        />
         <button
-          @click="agent.chat"
+          @click="sendMessage"
           :disabled="isStreaming"
         >
           {{ isStreaming ? '生成中...' : '发送消息' }}
@@ -776,8 +1081,9 @@ class SafeProtocol extends AGUIProtocol {
   import { useChatHelper, AGUIProtocol } from '@blueking/chat-helper';
 
   const isStreaming = ref(false);
+  const userInput = ref('');
 
-  const { agent, session } = useChatHelper({
+  const { agent, session, message } = useChatHelper({
     requestData: {
       urlPrefix: 'https://your-api-domain.com/api/',
       headers: () => ({
@@ -827,10 +1133,17 @@ class SafeProtocol extends AGUIProtocol {
 
   const createNewSession = () => {
     session.createSession({
-      title: `会话 ${new Date().toLocaleString()}`,
+      sessionName: `会话 ${new Date().toLocaleString()}`,
       sessionCode: `session_${Date.now()}`,
     });
   };
+
+  const sendMessage = () => {
+    if (session.current?.sessionCode && userInput.value.trim()) {
+      agent.chat(userInput.value, session.current.sessionCode);
+      userInput.value = ''; // 清空输入框
+    }
+  };
 </script>
 
 <style scoped>
@@ -902,7 +1215,7 @@ class SafeProtocol extends AGUIProtocol {
     <div class="messages">
       <div
         v-for="msg in message.list"
-        :key="msg.id"
+        :key="msg.messageId"
         class="message"
       >
         <template
@@ -941,6 +1254,12 @@ class SafeProtocol extends AGUIProtocol {
 
     <!-- 输入区域 -->
     <div class="input-area">
+      <input
+        v-model="userInput"
+        @keyup.enter="sendMessage"
+        placeholder="输入消息..."
+        :disabled="isStreaming"
+      />
       <button
         @click="sendMessage"
         :disabled="isStreaming"
@@ -969,6 +1288,7 @@ class SafeProtocol extends AGUIProtocol {
 
   const isStreaming = ref(false);
   const status = ref<{ type: string; message: string } | null>(null);
+  const userInput = ref('');
 
   // 自定义 Protocol，添加各种钩子
   class CustomChatProtocol extends AGUIProtocol {
@@ -1005,7 +1325,7 @@ class SafeProtocol extends AGUIProtocol {
     }
   }
 
-  const { agent } = useChatHelper({
+  const { agent, session, message } = useChatHelper({
     requestData: {
       urlPrefix: 'https://your-api-domain.com/api/',
     },
@@ -1045,7 +1365,10 @@ class SafeProtocol extends AGUIProtocol {
   });
 
   const sendMessage = () => {
-    agent.chat();
+    if (session.current?.sessionCode && userInput.value.trim()) {
+      agent.chat(userInput.value, session.current.sessionCode);
+      userInput.value = ''; // 清空输入框
+    }
   };
 
   const stopStreaming = () => {
@@ -1099,19 +1422,595 @@ class SafeProtocol extends AGUIProtocol {
 
 ```typescript
 import type {
+  // 主要配置和模块类型
   IUseChatHelperOptions,
   IAgentModule,
   ISessionModule,
   IMessageModule,
   IHttpModule,
+
+  // 核心数据类型
   IMessage,
   ISession,
-  MessageRole,
-  MessageStatus,
-  MessageContentType,
+  IAgentInfo,
+
+  // 消息相关枚举
+  MessageRole, // 消息角色：user, assistant, system, tool, activity, reasoning 等
+  MessageStatus, // 消息状态：pending, streaming, complete, error, stop
+  MessageType, // 消息类型：text, binary, function
+
+  // 协议相关
+  ISSEProtocol,
+  AGUIProtocol,
+
+  // 事件类型（用于自定义 Protocol）
+  IEvent,
+  IRunStartedEvent,
+  IRunFinishedEvent,
+  IRunErrorEvent,
+  ITextMessageChunkEvent,
+  IThinkingStartEvent,
+  IThinkingEndEvent,
+  IToolCallStartEvent,
+  // ... 更多事件类型
 } from '@blueking/chat-helper';
 ```
 
+### MessageRole 枚举
+
+消息支持多种角色类型：
+
+```typescript
+enum MessageRole {
+  User = 'user', // 用户消息
+  Assistant = 'assistant', // AI 助手消息
+  System = 'system', // 系统消息
+  Tool = 'tool', // 工具调用结果
+  Activity = 'activity', // 活动消息
+  Reasoning = 'reasoning', // 推理过程
+  Developer = 'developer', // 开发者消息
+  Guide = 'guide', // 引导消息
+  Info = 'info', // 信息消息
+  Pause = 'pause', // 暂停消息
+  Placeholder = 'placeholder', // 占位消息
+  Hidden = 'hidden', // 隐藏消息
+  HiddenUser = 'hidden-user', // 隐藏的用户消息
+  HiddenAssistant = 'hidden-assistant', // 隐藏的助手消息
+  HiddenSystem = 'hidden-system', // 隐藏的系统消息
+  HiddenGuide = 'hidden-guide', // 隐藏的引导消息
+  TemplateUser = 'template-user', // 用户消息模板
+  TemplateAssistant = 'template-assistant', // 助手消息模板
+  TemplateSystem = 'template-system', // 系统消息模板
+  TemplateGuide = 'template-guide', // 引导消息模板
+  TemplateHidden = 'template-hidden', // 隐藏消息模板
+}
+```
+
+### MessageStatus 枚举
+
+消息状态定义：
+
+```typescript
+enum MessageStatus {
+  Pending = 'pending', // 等待中
+  Streaming = 'streaming', // 流式传输中
+  Complete = 'complete', // 已完成
+  Error = 'error', // 错误
+  Stop = 'stop', // 已停止
+}
+```
+
+### IMessage 类型
+
+消息是联合类型，根据 `role` 字段不同有不同的结构：
+
+```typescript
+// 用户消息
+interface IUserMessage {
+  messageId?: string;
+  role: MessageRole.User;
+  status: MessageStatus;
+  content: string | IInputContent[]; // 支持文本或多媒体内容
+}
+
+// AI 助手消息
+interface IAssistantMessage {
+  messageId?: string;
+  role: MessageRole.Assistant;
+  status: MessageStatus;
+  content?: string;
+  toolCalls?: IToolCall[]; // 工具调用信息
+}
+
+// 工具消息
+interface IToolMessage {
+  messageId?: string;
+  role: MessageRole.Tool;
+  status: MessageStatus;
+  content: string;
+  toolCallId: string;
+  duration?: number;
+  error?: string;
+}
+
+// ... 更多消息类型
+```
+
+## API 参考
+
+### useChatHelper(options)
+
+创建 Chat Helper 实例。
+
+**参数：**
+
+- `options.requestData` (必需)
+
+  - `urlPrefix: string` - API 基础路径
+  - `data?: Record<string, unknown> | (() => Record<string, unknown>)` - 额外的请求数据
+  - `headers?: Record<string, string> | (() => Record<string, string>)` - 额外的请求头
+
+- `options.interceptors` (可选)
+
+  - `request?: (config: IRequestConfig) => IRequestConfig` - 请求拦截器
+  - `response?: (response: IResponse) => IResponse` - 响应拦截器
+
+- `options.protocol` (可选) - 自定义 SSE Protocol 实例，默认使用 `AGUIProtocol`
+
+**返回值：**
+
+```typescript
+{
+  agent: IAgentModule,      // Agent 模块
+  session: ISessionModule,  // Session 模块
+  message: IMessageModule,  // Message 模块
+  http: IHttpModule         // HTTP 模块
+}
+```
+
+### Agent 模块 API
+
+#### agent.info
+
+- **类型**：`Ref<IAgentInfo | null>`
+- **说明**：当前 Agent 的信息，包括名称、会话设置、预定义问题等
+
+#### agent.isInfoLoading
+
+- **类型**：`Ref<boolean>`
+- **说明**：Agent 信息是否正在加载
+
+#### agent.getAgentInfo()
+
+- **返回值**：`Promise<void>`
+- **说明**：获取 Agent 信息，结果保存在 `agent.info` 中
+
+#### agent.chat(userInput, sessionCode, url?, config?)
+
+- **参数**：
+  - `userInput: string` - 用户输入的消息内容
+  - `sessionCode: string` - 会话代码
+  - `url?: string` - 自定义聊天接口地址，默认为 `'chat_completion/'`
+  - `config?: IRequestConfig` - 额外的请求配置
+- **返回值**：`Promise<void>`
+- **说明**：开始与 AI 进行聊天，支持流式响应。会先创建一条用户消息，然后发起流式请求
+
+#### agent.stopChat()
+
+- **返回值**：`Promise<void>`
+- **说明**：停止当前的聊天流式响应
+
+### Session 模块 API
+
+#### session.list
+
+- **类型**：`Ref<ISession[]>`
+- **说明**：会话列表
+
+#### session.current
+
+- **类型**：`Ref<ISession | null>`
+- **说明**：当前选中的会话
+
+#### session.isListLoading / isCurrentLoading / isCreateLoading / isUpdateLoading / isDeleteLoading
+
+- **类型**：`Ref<boolean>`
+- **说明**：各操作的加载状态
+
+#### session.getSessions()
+
+- **返回值**：`Promise<void>`
+- **说明**：获取会话列表，结果保存在 `session.list` 中
+
+#### session.chooseSession(sessionCode)
+
+- **参数**：`sessionCode: string` - 会话代码
+- **返回值**：`Promise<void>`
+- **说明**：选择会话，会停止当前聊天、设置 `session.current`，并自动加载该会话的消息列表
+
+#### session.getSession(sessionCode)
+
+- **参数**：`sessionCode: string` - 会话代码
+- **返回值**：`Promise<void>`
+- **说明**：获取单个会话信息，结果保存在 `session.current` 中
+
+#### session.createSession(session)
+
+- **参数**：`session: ISession` - 会话数据
+- **返回值**：`Promise<void>`
+- **说明**：创建新会话，创建成功后会添加到列表并自动选中
+
+#### session.updateSession(session)
+
+- **参数**：`session: ISession` - 会话数据
+- **返回值**：`Promise<void>`
+- **说明**：更新会话信息
+
+#### session.deleteSession(sessionCode)
+
+- **参数**：`sessionCode: string` - 会话代码
+- **返回值**：`Promise<void>`
+- **说明**：删除会话，如果删除的是当前会话，会自动切换到第一个会话
+
+### Message 模块 API
+
+#### message.list
+
+- **类型**：`Ref<IMessage[]>`
+- **说明**：消息列表
+
+#### message.isListLoading / isDeleteLoading / isBatchDeleteLoading
+
+- **类型**：`Ref<boolean>`
+- **说明**：各操作的加载状态
+
+#### message.getMessages(sessionCode)
+
+- **参数**：`sessionCode: string` - 会话代码
+- **返回值**：`Promise<void>`
+- **说明**：获取指定会话的消息列表
+
+#### message.plusMessage(message)
+
+- **参数**：`message: IMessage` - 消息数据
+- **返回值**：`Promise<void>`
+- **说明**：添加新消息，会先调用接口创建，然后添加到列表最前面
+
+#### message.modifyMessage(message)
+
+- **参数**：`message: IMessage` - 消息数据
+- **返回值**：`void`
+- **说明**：修改消息（仅本地更新，不调用接口）
+
+#### message.deleteMessage(id)
+
+- **参数**：`id: string` - 消息 ID
+- **返回值**：`Promise<void>`
+- **说明**：删除单条消息
+
+#### message.batchDeleteMessages(ids)
+
+- **参数**：`ids: string[]` - 消息 ID 数组
+- **返回值**：`Promise<void>`
+- **说明**：批量删除多条消息
+
+#### message.getCurrentLoadingMessage()
+
+- **返回值**：`IMessage | undefined`
+- **说明**：获取当前正在加载或流式传输中的 AI 消息（状态为 Pending 或 Streaming）
+
+#### message.getMessageByMessageId(id)
+
+- **参数**：`id: string` - 消息 ID
+- **返回值**：`IMessage | undefined`
+- **说明**：根据消息 ID 从列表中查找消息
+
+## 最佳实践
+
+### 1. 错误处理
+
+建议在使用 API 时添加适当的错误处理：
+
+```typescript
+const { session } = useChatHelper({
+  /* ... */
+});
+
+const loadSessions = async () => {
+  try {
+    await session.getSessions();
+  } catch (error) {
+    console.error('加载会话列表失败:', error);
+    // 显示错误提示给用户
+  }
+};
+```
+
+### 2. 加载状态管理
+
+利用响应式的加载状态提供更好的用户体验：
+
+```vue
+<template>
+  <div>
+    <div v-if="session.isListLoading">
+      <Spinner />
+      加载中...
+    </div>
+    <ul v-else>
+      <li
+        v-for="item in session.list"
+        :key="item.sessionCode"
+      >
+        {{ item.sessionName }}
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+### 3. 会话切换
+
+切换会话时，`chooseSession` 会自动停止当前聊天并加载新会话的消息：
+
+```typescript
+// ✅ 推荐：使用 chooseSession
+await session.chooseSession(sessionCode);
+
+// ❌ 不推荐：手动操作
+agent.stopChat();
+session.current.value = session.list.value.find(s => s.sessionCode === sessionCode);
+message.getMessages(sessionCode);
+```
+
+### 4. 消息 ID 使用
+
+代码中使用 `messageId` 字段作为消息的唯一标识：
+
+```typescript
+// ✅ 正确
+message.deleteMessage(msg.messageId);
+
+// ❌ 错误
+message.deleteMessage(msg.id);
+```
+
+### 5. 动态请求配置
+
+对于需要动态获取的配置（如 token），使用函数形式：
+
+```typescript
+useChatHelper({
+  requestData: {
+    urlPrefix: 'https://api.example.com/',
+    // ✅ 使用函数动态获取
+    headers: () => ({
+      Authorization: `Bearer ${localStorage.getItem('token')}`,
+      'X-Request-ID': generateRequestId(),
+    }),
+  },
+});
+```
+
+### 6. Protocol 钩子函数
+
+使用 Protocol 钩子函数时，注意不要阻塞事件处理：
+
+```typescript
+new AGUIProtocol({
+  onMessage: async event => {
+    // ❌ 不推荐：阻塞事件处理
+    await someAsyncOperation();
+    console.log(event);
+  },
+
+  onMessage: event => {
+    // ✅ 推荐：快速处理，异步操作不阻塞
+    console.log(event);
+    someAsyncOperation(); // 不 await
+  },
+});
+```
+
+### 7. 内存管理
+
+在组件卸载时，记得停止正在进行的聊天：
+
+```typescript
+import { onUnmounted } from 'vue';
+
+const { agent } = useChatHelper({
+  /* ... */
+});
+
+onUnmounted(() => {
+  agent.stopChat();
+});
+```
+
+### 8. 消息状态判断
+
+使用枚举类型进行状态判断，避免硬编码字符串：
+
+```typescript
+import { MessageStatus, MessageRole } from '@blueking/chat-helper';
+
+// ✅ 推荐：使用枚举
+if (msg.status === MessageStatus.Streaming && msg.role === MessageRole.Assistant) {
+  // 显示流式动画
+}
+
+// ❌ 不推荐：硬编码字符串
+if (msg.status === 'streaming' && msg.role === 'assistant') {
+  // 显示流式动画
+}
+```
+
+## 常见问题
+
+### Q: 如何处理流式响应中的错误？
+
+A: 使用 Protocol 的 `onError` 钩子函数：
+
+```typescript
+useChatHelper({
+  requestData: {
+    /* ... */
+  },
+  protocol: new AGUIProtocol({
+    onError: error => {
+      console.error('流式响应错误:', error);
+      // 显示错误提示
+      showErrorMessage('AI 响应出错，请重试');
+    },
+  }),
+});
+```
+
+### Q: 如何自定义不同端点的聊天行为？
+
+A: 使用 `agent.chat` 的 `url` 和 `config` 参数：
+
+```typescript
+// 使用不同的端点
+agent.chat(userInput, sessionCode, 'custom_chat/');
+
+// 添加自定义参数
+agent.chat(userInput, sessionCode, undefined, {
+  data: {
+    temperature: 0.8,
+    model: 'gpt-4',
+  },
+});
+```
+
+### Q: 消息列表如何实现自动滚动到底部？
+
+A: 使用 Vue 的 `watch` 监听消息列表变化：
+
+```typescript
+import { watch, nextTick, ref } from 'vue';
+
+const messageContainer = ref<HTMLElement>();
+const { message } = useChatHelper({
+  /* ... */
+});
+
+watch(
+  () => message.list.value.length,
+  async () => {
+    await nextTick();
+    messageContainer.value?.scrollTo({
+      top: messageContainer.value.scrollHeight,
+      behavior: 'smooth',
+    });
+  },
+);
+```
+
+### Q: 如何判断 AI 是否正在回复？
+
+A: 使用 `message.getCurrentLoadingMessage()` 方法：
+
+```typescript
+const { message } = useChatHelper({
+  /* ... */
+});
+
+const isAIResponding = computed(() => {
+  return message.getCurrentLoadingMessage() !== undefined;
+});
+```
+
+### Q: 如何实现多租户或多应用场景？
+
+A: 使用动态的 `data` 配置：
+
+```typescript
+const currentAppId = ref('app-1');
+
+useChatHelper({
+  requestData: {
+    urlPrefix: 'https://api.example.com/',
+    data: () => ({
+      app_id: currentAppId.value,
+      tenant_id: getTenantId(),
+    }),
+  },
+});
+```
+
+### Q: 如何自定义流式事件的处理逻辑？
+
+A: 继承 `AGUIProtocol` 并重写对应的事件处理方法：
+
+```typescript
+class MyProtocol extends AGUIProtocol {
+  handleTextMessageChunkEvent(event: ITextMessageChunkEvent) {
+    // 自定义逻辑：例如敏感词过滤
+    const filteredText = filterSensitiveWords(event.delta);
+
+    // 调用父类方法继续处理
+    super.handleTextMessageChunkEvent({
+      ...event,
+      delta: filteredText,
+    });
+  }
+}
+
+useChatHelper({
+  requestData: {
+    /* ... */
+  },
+  protocol: new MyProtocol(),
+});
+```
+
+### Q: 如何实现消息的本地缓存？
+
+A: 使用 `watch` 监听消息变化并保存到本地存储：
+
+```typescript
+import { watch } from 'vue';
+
+const { message, session } = useChatHelper({
+  /* ... */
+});
+
+// 监听消息变化并缓存
+watch(
+  () => message.list.value,
+  newList => {
+    if (session.current?.sessionCode) {
+      localStorage.setItem(`messages_${session.current.sessionCode}`, JSON.stringify(newList));
+    }
+  },
+  { deep: true },
+);
+
+// 加载缓存
+const loadCachedMessages = (sessionCode: string) => {
+  const cached = localStorage.getItem(`messages_${sessionCode}`);
+  if (cached) {
+    message.list.value = JSON.parse(cached);
+  }
+};
+```
+
+## 贡献指南
+
+欢迎提交 Issue 和 Pull Request！
+
+在提交 PR 之前，请确保：
+
+1. 代码通过 ESLint 检查
+2. 添加了必要的类型定义
+3. 更新了相关文档
+
+## 更新日志
+
+查看 [CHANGELOG.md](./CHANGELOG.md) 了解版本更新历史。
+
 ## License
 
 MIT License