@blueking/chat-helper 0.0.1-beta.1

package/README.md

@@ -0,0 +1,1112 @@
+# @blueking/chat-helper
+
+一个用于 Vue3 的聊天助手工具包，提供完整的 AI 对话功能，支持流式响应、会话管理、消息管理等功能。
+
+## 安装
+
+```bash
+npm install @blueking/chat-helper
+```
+
+## 快速开始
+
+```typescript
+import { useChatHelper } from '@blueking/chat-helper';
+
+// 在 Vue 组件中使用
+const chatHelper = useChatHelper({
+  requestData: {
+    urlPrefix: 'https://your-api-domain.com/api/',
+    headers: {
+      Authorization: 'Bearer your-token',
+    },
+  },
+});
+
+// 解构返回的模块
+const { agent, session, message, http } = chatHelper;
+```
+
+## useChatHelper 返回数据说明
+
+`useChatHelper` 返回一个包含四个模块的对象：
+
+### 1. agent - 代理模块
+
+管理 AI 代理相关功能。
+
+```typescript
+const { agent } = chatHelper;
+
+// 响应式数据
+agent.info; // Ref<IAgentInfo | null> - agent 信息
+agent.isInfoLoading; // Ref<boolean> - agent 信息加载状态
+
+// 方法
+agent.getAgentInfo(); // () => Promise<void> - 获取 agent 信息
+agent.chat(); // () => void - 开始聊天（流式响应）
+agent.stopChat(); // () => Promise<void> - 停止聊天
+```
+
+**使用示例**：
+
+```vue
+<template>
+  <div>
+    <div v-if="agent.isInfoLoading">加载中...</div>
+    <div v-else-if="agent.info">
+      <h2>{{ agent.info.name }}</h2>
+      <p>{{ agent.info.description }}</p>
+    </div>
+    <button @click="startChat">开始对话</button>
+    <button @click="agent.stopChat">停止对话</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { onMounted } from 'vue';
+  import { useChatHelper } from '@blueking/chat-helper';
+
+  const { agent } = useChatHelper({
+    /* ... */
+  });
+
+  onMounted(() => {
+    agent.getAgentInfo();
+  });
+
+  const startChat = () => {
+    agent.chat();
+  };
+</script>
+```
+
+### 2. session - 会话模块
+
+管理聊天会话的创建、切换、更新和删除。
+
+```typescript
+const { session } = chatHelper;
+
+// 响应式数据
+session.list; // Ref<ISession[]> - 会话列表
+session.current; // Ref<ISession | null> - 当前会话
+session.isListLoading; // Ref<boolean> - 列表加载状态
+session.isCurrentLoading; // Ref<boolean> - 当前会话加载状态
+session.isCreateLoading; // Ref<boolean> - 创建会话加载状态
+session.isUpdateLoading; // Ref<boolean> - 更新会话加载状态
+session.isDeleteLoading; // Ref<boolean> - 删除会话加载状态
+
+// 方法
+session.getSessions(); // () => Promise<void> - 获取会话列表
+session.chooseSession(sessionCode); // (sessionCode: string) => Promise<void> - 选择会话
+session.getSession(sessionCode); // (sessionCode: string) => Promise<void> - 获取单个会话
+session.createSession(session); // (session: ISession) => Promise<void> - 创建会话
+session.updateSession(session); // (session: ISession) => Promise<void> - 更新会话
+session.deleteSession(sessionCode); // (sessionCode: string) => Promise<void> - 删除会话
+```
+
+**使用示例**：
+
+```vue
+<template>
+  <div>
+    <ul v-if="!session.isListLoading">
+      <li
+        v-for="item in session.list"
+        :key="item.sessionCode"
+        @click="session.chooseSession(item.sessionCode)"
+        :class="{ active: session.current?.sessionCode === item.sessionCode }"
+      >
+        {{ item.title }}
+      </li>
+    </ul>
+    <button @click="createNewSession">新建会话</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { onMounted } from 'vue';
+  import { useChatHelper } from '@blueking/chat-helper';
+
+  const { session } = useChatHelper({
+    /* ... */
+  });
+
+  onMounted(() => {
+    session.getSessions();
+  });
+
+  const createNewSession = () => {
+    session.createSession({
+      title: '新会话',
+      // ... 其他会话属性
+    });
+  };
+</script>
+```
+
+### 3. message - 消息模块
+
+管理聊天消息的获取、添加、修改和删除。
+
+```typescript
+const { message } = chatHelper;
+
+// 响应式数据
+message.list; // Ref<IMessage[]> - 消息列表
+message.isListLoading; // Ref<boolean> - 列表加载状态
+message.isDeleteLoading; // Ref<boolean> - 删除加载状态
+
+// 方法
+message.getMessages(sessionCode); // (sessionCode: string) => Promise<void> - 获取消息列表
+message.plusMessage(message); // (message: IMessage) => void - 添加消息
+message.modifyMessage(message); // (message: IMessage) => void - 修改消息
+message.deleteMessage(id); // (id: number) => Promise<void> - 删除消息
+message.batchDeleteMessages(ids); // (ids: number[]) => Promise<void> - 批量删除消息
+message.getCurrentLoadingMessage(); // () => IMessage | undefined - 获取当前加载中的消息
+message.getMessageById(id); // (id: number) => IMessage | undefined - 根据 ID 获取消息
+```
+
+**使用示例**：
+
+```vue
+<template>
+  <div class="message-list">
+    <div
+      v-for="msg in message.list"
+      :key="msg.id"
+      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>
+      </div>
+      <button @click="message.deleteMessage(msg.id)">删除</button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { useChatHelper } from '@blueking/chat-helper';
+
+  const { message } = useChatHelper({
+    /* ... */
+  });
+</script>
+```
+
+### 4. http - HTTP 模块
+
+底层 HTTP 请求模块，提供各种 API 调用方法。
+
+```typescript
+const { http } = chatHelper;
+
+// 包含以下子模块：
+http.agent; // Agent API
+http.session; // Session API
+http.message; // Message API
+```
+
+一般情况下，您不需要直接使用 `http` 模块，因为 `agent`、`session` 和 `message` 模块已经封装了常用的业务逻辑。
+
+## 配置选项
+
+### requestData（必需）
+
+配置 HTTP 请求的基础信息。
+
+```typescript
+useChatHelper({
+  requestData: {
+    // API 基础路径（必需）
+    urlPrefix: 'https://your-api-domain.com/api/',
+
+    // 额外的请求数据（可选）
+    data: {
+      appId: 'your-app-id',
+      version: '1.0.0',
+    },
+    // 或者使用函数动态返回
+    data: () => ({
+      appId: getAppId(),
+      timestamp: Date.now(),
+    }),
+
+    // 额外的请求头（可选）
+    headers: {
+      Authorization: 'Bearer your-token',
+      'X-Custom-Header': 'value',
+    },
+    // 或者使用函数动态返回
+    headers: () => ({
+      Authorization: `Bearer ${getToken()}`,
+      'X-Request-ID': generateRequestId(),
+    }),
+  },
+});
+```
+
+### interceptors（可选）
+
+配置请求和响应拦截器，用于统一处理请求和响应。
+
+```typescript
+useChatHelper({
+  requestData: {
+    /* ... */
+  },
+  interceptors: {
+    // 请求拦截器
+    request: config => {
+      // 在发送请求之前做些什么
+      console.log('Request:', config);
+
+      // 添加自定义请求头
+      config.headers = {
+        ...config.headers,
+        'X-Request-Time': new Date().toISOString(),
+      };
+
+      // 必须返回 config
+      return config;
+    },
+
+    // 响应拦截器
+    response: response => {
+      // 对响应数据做些什么
+      console.log('Response:', response);
+
+      // 可以在这里做统一的错误处理
+      if (response.data.code !== 0) {
+        console.error('API Error:', response.data.message);
+      }
+
+      // 必须返回 response
+      return response;
+    },
+  },
+});
+```
+
+**拦截器使用场景**：
+
+1. **请求拦截器**：
+
+   - 添加认证 token
+   - 添加请求时间戳
+   - 添加请求 ID
+   - 记录请求日志
+   - 请求参数加密
+
+2. **响应拦截器**：
+   - 统一错误处理
+   - 响应数据解密
+   - 数据格式转换
+   - 记录响应日志
+   - 刷新 token
+
+### protocol（可选）
+
+自定义 SSE（Server-Sent Events）协议处理器，用于处理流式响应。
+
+#### 使用默认 protocol
+
+如果不提供 `protocol` 配置，系统会使用默认的 `AGUIProtocol`：
+
+```typescript
+useChatHelper({
+  requestData: {
+    /* ... */
+  },
+  // 不配置 protocol，使用默认的 AGUIProtocol
+});
+```
+
+#### 使用 protocol 钩子函数
+
+`AGUIProtocol` 提供了四个生命周期钩子函数，您可以在创建 protocol 实例时传入：
+
+```typescript
+import { useChatHelper, AGUIProtocol } from '@blueking/chat-helper';
+
+const { agent } = useChatHelper({
+  requestData: {
+    urlPrefix: 'https://your-api-domain.com/api/',
+  },
+  protocol: new AGUIProtocol({
+    // 流式响应开始时调用
+    onStart: () => {
+      console.log('开始接收流式响应');
+      // 显示加载动画
+      // 禁用发送按钮
+    },
+    // 每次接收到事件时调用
+    onMessage: event => {
+      console.log('接收到事件:', event);
+      // 记录事件日志
+      // 更新进度条
+      // 触发自定义事件
+    },
+    // 流式响应完成时调用
+    onDone: () => {
+      console.log('流式响应完成');
+      // 隐藏加载动画
+      // 启用发送按钮
+      // 播放完成提示音
+    },
+    // 发生错误时调用
+    onError: error => {
+      console.error('流式响应错误:', error);
+      // 显示错误提示
+      // 恢复 UI 状态
+      // 上报错误日志
+    },
+  }),
+});
+```
+
+**钩子函数使用场景**：
+
+- **onStart**：显示加载状态、禁用输入框、重置 UI 状态
+- **onMessage**：记录事件日志、更新进度、触发自定义事件、实时分析数据
+- **onDone**：隐藏加载状态、启用输入框、播放提示音、保存会话历史
+- **onError**：显示错误提示、恢复 UI 状态、上报错误、重试逻辑
+
+#### 自定义 protocol
+
+如果您需要自定义流式响应的处理逻辑，可以实现 `ISSEProtocol` 接口：
+
+```typescript
+import { useChatHelper, type ISSEProtocol, type IMessageModule } from '@blueking/chat-helper';
+
+class CustomProtocol implements ISSEProtocol {
+  private messageModule: IMessageModule;
+
+  constructor({ message }: { message: IMessageModule }) {
+    this.messageModule = message;
+  }
+
+  onStart() {
+    console.log('Stream started');
+    // 在流式响应开始时执行
+  }
+
+  onMessage(event: unknown) {
+    console.log('Received event:', event);
+    // 处理每个 SSE 事件
+    // 您可以根据事件类型更新消息列表
+    this.messageModule.plusMessage(/* ... */);
+  }
+
+  onDone() {
+    console.log('Stream completed');
+    // 在流式响应完成时执行
+  }
+
+  onError(error: Error) {
+    console.error('Stream error:', error);
+    // 处理错误
+  }
+}
+
+// 使用自定义 protocol
+const { agent, message } = useChatHelper({
+  requestData: {
+    /* ... */
+  },
+  protocol: new CustomProtocol({ message }),
+});
+```
+
+#### 扩展默认 protocol - 重写事件处理钩子
+
+`AGUIProtocol` 为每种事件类型都提供了对应的处理方法（钩子），您可以继承并重写这些方法来自定义行为：
+
+```typescript
+import {
+  AGUIProtocol,
+  type ITextMessageChunkEvent,
+  type IRunErrorEvent,
+  type IThinkingStartEvent,
+  type IToolCallStartEvent,
+} from '@blueking/chat-helper';
+
+class MyCustomProtocol extends AGUIProtocol {
+  // 重写文本消息流式处理
+  handleTextMessageChunkEvent(event: ITextMessageChunkEvent) {
+    // 自定义处理逻辑
+    console.log('接收到文本块:', event.delta);
+
+    // 调用父类方法（保留默认行为）
+    super.handleTextMessageChunkEvent(event);
+
+    // 额外的自定义逻辑
+    // 例如：实时语音播报、敏感词过滤等
+    if (event.delta.includes('重要')) {
+      this.highlightImportantContent(event.messageId);
+    }
+  }
+
+  // 重写思考开始事件
+  handleThinkingStartEvent(event: IThinkingStartEvent) {
+    console.log('AI 开始思考:', event.title);
+
+    // 显示思考动画
+    this.showThinkingAnimation();
+
+    // 调用父类方法
+    super.handleThinkingStartEvent(event);
+  }
+
+  // 重写工具调用开始事件
+  handleToolCallStartEvent(event: IToolCallStartEvent) {
+    console.log('调用工具:', event.toolCallName);
+
+    // 显示工具调用提示
+    this.showToolCallNotification(event.toolCallName);
+
+    // 调用父类方法
+    super.handleToolCallStartEvent(event);
+  }
+
+  // 重写错误处理
+  handleRunErrorEvent(event: IRunErrorEvent) {
+    console.error('运行错误:', event.message);
+
+    // 自定义错误提示
+    this.showCustomErrorMessage(event.message);
+
+    // 上报错误
+    this.reportError(event);
+
+    // 调用父类方法
+    super.handleRunErrorEvent(event);
+  }
+
+  // 自定义辅助方法
+  private highlightImportantContent(messageId: string) {
+    // 高亮重要内容
+  }
+
+  private showThinkingAnimation() {
+    // 显示思考动画
+  }
+
+  private showToolCallNotification(toolName: string) {
+    // 显示工具调用通知
+  }
+
+  private showCustomErrorMessage(message: string) {
+    // 显示自定义错误消息
+  }
+
+  private reportError(event: IRunErrorEvent) {
+    // 上报错误到监控系统
+  }
+}
+
+const { agent } = useChatHelper({
+  requestData: {
+    /* ... */
+  },
+  protocol: new MyCustomProtocol({
+    onStart: () => console.log('开始对话'),
+    onDone: () => console.log('对话完成'),
+  }),
+});
+```
+
+**常用的事件处理钩子**：
+
+| 钩子方法                                | 说明               | 使用场景               |
+| --------------------------------------- | ------------------ | ---------------------- |
+| `handleRunStartedEvent`                 | 运行开始           | 创建新消息、初始化状态 |
+| `handleRunFinishedEvent`                | 运行完成           | 更新消息状态、保存历史 |
+| `handleRunErrorEvent`                   | 运行错误           | 错误提示、状态恢复     |
+| `handleTextMessageStartEvent`           | 文本消息开始       | 准备文本容器           |
+| `handleTextMessageChunkEvent`           | 文本消息块（流式） | 实时显示文本、语音播报 |
+| `handleTextMessageEndEvent`             | 文本消息结束       | 完成文本渲染           |
+| `handleThinkingStartEvent`              | 思考开始           | 显示思考动画           |
+| `handleThinkingTextMessageContentEvent` | 思考内容           | 显示思考过程           |
+| `handleThinkingEndEvent`                | 思考结束           | 隐藏思考动画、统计时间 |
+| `handleToolCallStartEvent`              | 工具调用开始       | 显示工具调用提示       |
+| `handleToolCallArgsEvent`               | 工具参数           | 显示调用参数           |
+| `handleToolCallResultEvent`             | 工具结果           | 显示调用结果           |
+| `handleToolCallEndEvent`                | 工具调用结束       | 完成工具调用展示       |
+| `handleMessagesSnapshotEvent`           | 消息快照           | 同步多端消息状态       |
+| `handleActivityDeltaEvent`              | 活动增量更新       | 实时更新活动状态       |
+| `handleActivitySnapshotEvent`           | 活动快照           | 获取完整活动状态       |
+
+**实际应用示例**：
+
+```typescript
+class EnhancedProtocol extends AGUIProtocol {
+  private audioPlayer: AudioPlayer;
+  private analytics: Analytics;
+
+  constructor(options) {
+    super(options);
+    this.audioPlayer = new AudioPlayer();
+    this.analytics = new Analytics();
+  }
+
+  // 实时语音播报
+  handleTextMessageChunkEvent(event: ITextMessageChunkEvent) {
+    super.handleTextMessageChunkEvent(event);
+
+    // 将文本转换为语音播放
+    if (this.audioPlayer.isEnabled()) {
+      this.audioPlayer.speak(event.delta);
+    }
+  }
+
+  // 统计思考时间
+  handleThinkingEndEvent(event: IThinkingEndEvent) {
+    super.handleThinkingEndEvent(event);
+
+    // 记录思考时长用于分析
+    this.analytics.trackThinkingTime(event.timestamp);
+  }
+
+  // 工具调用监控
+  handleToolCallStartEvent(event: IToolCallStartEvent) {
+    super.handleToolCallStartEvent(event);
+
+    // 记录工具使用情况
+    this.analytics.trackToolUsage(event.toolCallName);
+
+    // 显示工具调用进度
+    showNotification(`正在调用工具: ${event.toolCallName}`);
+  }
+}
+```
+
+**钩子函数最佳实践**：
+
+1. **始终调用父类方法**：重写钩子时，记得调用 `super.handleXxxEvent(event)` 以保留默认行为
+2. **避免阻塞操作**：钩子函数应该快速执行，避免长时间运行的同步操作
+3. **错误处理**：在钩子中添加 try-catch，避免错误影响整体流程
+4. **按需重写**：只重写需要自定义的钩子，不需要重写所有方法
+5. **类型安全**：使用 TypeScript 类型定义，确保事件参数类型正确
+
+```typescript
+class SafeProtocol extends AGUIProtocol {
+  handleTextMessageChunkEvent(event: ITextMessageChunkEvent) {
+    try {
+      // 自定义逻辑
+      this.customLogic(event);
+
+      // 调用父类方法
+      super.handleTextMessageChunkEvent(event);
+    } catch (error) {
+      console.error('处理文本消息块时出错:', error);
+      // 即使出错也要调用父类方法，保证基本功能
+      super.handleTextMessageChunkEvent(event);
+    }
+  }
+
+  private customLogic(event: ITextMessageChunkEvent) {
+    // 您的自定义逻辑
+  }
+}
+```
+
+**AGUIProtocol 支持的所有事件类型**：
+
+<details>
+<summary>点击展开完整事件列表</summary>
+
+**运行相关事件**：
+
+- `RunStarted` - 运行开始，创建新的 AI 响应消息
+- `RunFinished` - 运行完成，标记消息为完成状态
+- `RunError` - 运行错误，显示错误信息
+
+**文本消息事件**：
+
+- `TextMessageStart` - 文本消息开始，创建文本内容容器
+- `TextMessageChunk` - 文本消息块，流式接收文本内容（最常用）
+- `TextMessageContent` - 文本消息内容，追加文本内容
+- `TextMessageEnd` - 文本消息结束，标记文本为完成状态
+
+**思考过程事件**：
+
+- `ThinkingStart` - 思考开始，显示 AI 思考标题
+- `ThinkingTextMessageStart` - 思考文本开始
+- `ThinkingTextMessageContent` - 思考文本内容，流式接收思考过程
+- `ThinkingTextMessageEnd` - 思考文本结束
+- `ThinkingEnd` - 思考结束，计算思考时长
+
+**工具调用事件**：
+
+- `ToolCallStart` - 工具调用开始，显示调用的工具名称
+- `ToolCallChunk` - 工具调用块，流式接收调用信息
+- `ToolCallArgs` - 工具参数，接收工具调用参数
+- `ToolCallResult` - 工具结果，接收工具执行结果
+- `ToolCallEnd` - 工具调用结束，标记工具调用完成
+
+**步骤相关事件**：
+
+- `StepStarted` - 步骤开始，多步骤任务中的单步开始
+- `StepFinished` - 步骤完成，单步任务完成
+
+**状态同步事件**：
+
+- `MessagesSnapshot` - 消息快照，用于多端消息同步
+- `StateSnapshot` - 状态快照，完整状态信息
+- `StateDelta` - 状态增量更新，使用 JSON Patch 格式
+- `ActivitySnapshot` - 活动快照，完整活动信息
+- `ActivityDelta` - 活动增量更新，使用 JSON Patch 格式
+
+**其他事件**：
+
+- `Raw` - 原始事件，透传底层 AI 服务的原始事件
+- `Custom` - 自定义事件，用户自定义的事件类型
+
+</details>
+
+## 完整示例
+
+以下是一个完整的聊天应用示例：
+
+```vue
+<template>
+  <div class="chat-app">
+    <!-- 会话列表 -->
+    <aside class="session-list">
+      <button @click="createNewSession">新建会话</button>
+      <ul>
+        <li
+          v-for="item in session.list"
+          :key="item.sessionCode"
+          @click="session.chooseSession(item.sessionCode)"
+          :class="{ active: session.current?.sessionCode === item.sessionCode }"
+        >
+          {{ item.title }}
+          <button @click.stop="session.deleteSession(item.sessionCode)">删除</button>
+        </li>
+      </ul>
+    </aside>
+
+    <!-- 消息区域 -->
+    <main class="message-area">
+      <div v-if="message.isListLoading">加载中...</div>
+      <div
+        v-else
+        class="message-list"
+      >
+        <div
+          v-for="msg in message.list"
+          :key="msg.id"
+          :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>
+          </div>
+          <button @click="message.deleteMessage(msg.id)">删除</button>
+        </div>
+      </div>
+
+      <!-- 输入区域 -->
+      <div class="input-area">
+        <button
+          @click="agent.chat"
+          :disabled="isStreaming"
+        >
+          {{ isStreaming ? '生成中...' : '发送消息' }}
+        </button>
+        <button
+          @click="agent.stopChat"
+          :disabled="!isStreaming"
+        >
+          停止生成
+        </button>
+      </div>
+    </main>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { onMounted, ref } from 'vue';
+  import { useChatHelper, AGUIProtocol } from '@blueking/chat-helper';
+
+  const isStreaming = ref(false);
+
+  const { agent, session } = useChatHelper({
+    requestData: {
+      urlPrefix: 'https://your-api-domain.com/api/',
+      headers: () => ({
+        Authorization: `Bearer ${localStorage.getItem('token')}`,
+      }),
+    },
+    interceptors: {
+      request: config => {
+        console.log('Request:', config.url);
+        return config;
+      },
+      response: response => {
+        if (response.data.code !== 0) {
+          console.error('API Error:', response.data.message);
+        }
+        return response;
+      },
+    },
+    protocol: new AGUIProtocol({
+      onStart: () => {
+        isStreaming.value = true;
+        console.log('开始接收 AI 响应');
+      },
+      onMessage: event => {
+        // 可以在这里添加自定义事件处理
+        console.log('收到事件:', event.type);
+      },
+      onDone: () => {
+        isStreaming.value = false;
+        console.log('AI 响应完成');
+      },
+      onError: error => {
+        isStreaming.value = false;
+        console.error('AI 响应错误:', error);
+        alert('发生错误，请重试');
+      },
+    }),
+  });
+
+  onMounted(async () => {
+    await agent.getAgentInfo();
+    await session.getSessions();
+    if (session.list.value.length > 0) {
+      await session.chooseSession(session.list.value[0].sessionCode);
+    }
+  });
+
+  const createNewSession = () => {
+    session.createSession({
+      title: `会话 ${new Date().toLocaleString()}`,
+      sessionCode: `session_${Date.now()}`,
+    });
+  };
+</script>
+
+<style scoped>
+  .chat-app {
+    display: flex;
+    height: 100vh;
+  }
+
+  .session-list {
+    width: 250px;
+    border-right: 1px solid #ddd;
+    padding: 20px;
+  }
+
+  .message-area {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    padding: 20px;
+  }
+
+  .message-list {
+    flex: 1;
+    overflow-y: auto;
+  }
+
+  .message-item {
+    margin-bottom: 20px;
+    padding: 10px;
+    border-radius: 8px;
+  }
+
+  .message-item.user {
+    background-color: #e3f2fd;
+    margin-left: 20%;
+  }
+
+  .message-item.assistant {
+    background-color: #f5f5f5;
+    margin-right: 20%;
+  }
+
+  .input-area {
+    display: flex;
+    gap: 10px;
+    padding-top: 20px;
+    border-top: 1px solid #ddd;
+  }
+</style>
+```
+
+## 钩子函数综合示例
+
+以下是一个结合所有钩子函数的实际应用示例：
+
+```vue
+<template>
+  <div class="chat-container">
+    <!-- 状态指示器 -->
+    <div
+      v-if="status"
+      class="status-bar"
+      :class="status.type"
+    >
+      {{ status.message }}
+    </div>
+
+    <!-- 消息列表 -->
+    <div class="messages">
+      <div
+        v-for="msg in message.list"
+        :key="msg.id"
+        class="message"
+      >
+        <template
+          v-for="content in msg.content"
+          :key="content.id"
+        >
+          <!-- 显示思考过程 -->
+          <div
+            v-if="content.type === 'thinking'"
+            class="thinking"
+          >
+            <span class="icon">🤔</span>
+            <strong>{{ content.data.title }}</strong>
+            <span v-if="content.data.duration"> ({{ content.data.duration }}ms) </span>
+          </div>
+
+          <!-- 显示工具调用 -->
+          <div
+            v-if="content.type === 'tool_call'"
+            class="tool-call"
+          >
+            <span class="icon">🔧</span>
+            <strong>{{ content.data.toolCallName }}</strong>
+          </div>
+
+          <!-- 显示文本内容 -->
+          <div
+            v-if="content.type === 'text'"
+            class="text"
+          >
+            {{ content.data }}
+          </div>
+        </template>
+      </div>
+    </div>
+
+    <!-- 输入区域 -->
+    <div class="input-area">
+      <button
+        @click="sendMessage"
+        :disabled="isStreaming"
+      >
+        发送
+      </button>
+      <button
+        @click="stopStreaming"
+        :disabled="!isStreaming"
+      >
+        停止
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import {
+    useChatHelper,
+    AGUIProtocol,
+    type IThinkingStartEvent,
+    type IToolCallStartEvent,
+    type IRunErrorEvent,
+  } from '@blueking/chat-helper';
+
+  const isStreaming = ref(false);
+  const status = ref<{ type: string; message: string } | null>(null);
+
+  // 自定义 Protocol，添加各种钩子
+  class CustomChatProtocol extends AGUIProtocol {
+    // 思考开始时显示通知
+    handleThinkingStartEvent(event: IThinkingStartEvent) {
+      status.value = {
+        type: 'thinking',
+        message: `AI 正在思考: ${event.title}`,
+      };
+      super.handleThinkingStartEvent(event);
+    }
+
+    // 工具调用时显示通知
+    handleToolCallStartEvent(event: IToolCallStartEvent) {
+      status.value = {
+        type: 'tool',
+        message: `正在调用工具: ${event.toolCallName}`,
+      };
+      super.handleToolCallStartEvent(event);
+    }
+
+    // 错误处理
+    handleRunErrorEvent(event: IRunErrorEvent) {
+      status.value = {
+        type: 'error',
+        message: `错误: ${event.message}`,
+      };
+      super.handleRunErrorEvent(event);
+
+      // 3秒后清除错误提示
+      setTimeout(() => {
+        status.value = null;
+      }, 3000);
+    }
+  }
+
+  const { agent } = useChatHelper({
+    requestData: {
+      urlPrefix: 'https://your-api-domain.com/api/',
+    },
+    protocol: new CustomChatProtocol({
+      // 开始接收响应
+      onStart: () => {
+        isStreaming.value = true;
+        status.value = {
+          type: 'streaming',
+          message: '正在接收 AI 响应...',
+        };
+      },
+      // 每个事件
+      onMessage: event => {
+        console.log('事件:', event);
+      },
+      // 响应完成
+      onDone: () => {
+        isStreaming.value = false;
+        status.value = {
+          type: 'success',
+          message: 'AI 响应完成',
+        };
+        setTimeout(() => {
+          status.value = null;
+        }, 2000);
+      },
+      // 响应错误
+      onError: error => {
+        isStreaming.value = false;
+        status.value = {
+          type: 'error',
+          message: `连接错误: ${error.message}`,
+        };
+      },
+    }),
+  });
+
+  const sendMessage = () => {
+    agent.chat();
+  };
+
+  const stopStreaming = () => {
+    agent.stopChat();
+  };
+</script>
+
+<style scoped>
+  .status-bar {
+    padding: 10px;
+    margin-bottom: 10px;
+    border-radius: 4px;
+  }
+
+  .status-bar.thinking {
+    background-color: #e3f2fd;
+  }
+
+  .status-bar.tool {
+    background-color: #fff3e0;
+  }
+
+  .status-bar.error {
+    background-color: #ffebee;
+    color: #c62828;
+  }
+
+  .status-bar.success {
+    background-color: #e8f5e9;
+  }
+
+  .thinking {
+    background-color: #f5f5f5;
+    padding: 8px;
+    margin: 4px 0;
+    border-radius: 4px;
+  }
+
+  .tool-call {
+    background-color: #fff3e0;
+    padding: 8px;
+    margin: 4px 0;
+    border-radius: 4px;
+  }
+</style>
+```
+
+## 类型定义
+
+所有类型都已导出，您可以在 TypeScript 项目中使用：
+
+```typescript
+import type {
+  IUseChatHelperOptions,
+  IAgentModule,
+  ISessionModule,
+  IMessageModule,
+  IHttpModule,
+  IMessage,
+  ISession,
+  MessageRole,
+  MessageStatus,
+  MessageContentType,
+} from '@blueking/chat-helper';
+```
+
+## License
+
+MIT License
+
+Copyright (C) 2021 THL A29 Limited, a Tencent company. All rights reserved.