agent-configs 1.0.0

package/skills/bk-chat-helper/SKILL.md

@@ -0,0 +1,398 @@
+---
+name: bk-chat-helper
+description: 蓝鲸智云 AI Chat Helper SDK 使用指南，提供 AI 对话的业务逻辑层（会话管理、消息管理、流式响应、Agent 集成）。**必须与 bk-chat-x skill 配合使用**：chat-x 负责 UI 渲染，chat-helper 负责状态和 API。当用户开发 AI 小鲸、智能体、AI 聊天功能时，应同时参考这两个 skill。
+metadata:
+  author: blueking
+  version: "1.0"
+---
+
+# @blueking/chat-helper SDK 使用指南
+
+## 快速开始
+
+### 安装
+
+```bash
+pnpm add @blueking/chat-helper
+```
+
+### 基础配置
+
+```typescript
+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;
+```
+
+## 核心架构
+
+`chat-helper` 采用**中介者模式**协调模块通信，核心模块：
+
+| 模块 | 职责 | 响应式数据 |
+|------|------|-----------|
+| agent | AI 代理管理、聊天发送 | `info`, `isInfoLoading`, `isChatting` |
+| session | 会话 CRUD、切换 | `list`, `current`, `isXxxLoading` |
+| message | 消息 CRUD、状态管理 | `list`, `isListLoading` |
+| http | 底层 HTTP 请求 | - |
+
+**数据流向**：
+```
+用户操作 → Agent/Session/Message → Mediator → HTTP → 后端 API
+                    ↑                                      ↓
+                    ←────────── 流式事件/响应数据 ←─────────
+```
+
+## 模块 API 速查
+
+### Agent 模块
+
+```typescript
+// 响应式数据
+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 模块
+
+```typescript
+// 响应式数据
+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 模块
+
+```typescript
+// 响应式数据
+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 获取消息
+```
+
+## 与 chat-x 组件集成
+
+### 完整集成示例
+
+```vue
+<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>
+```
+
+### 状态映射
+
+| chatHelper 状态 | chat-x MessageStatus | 场景 |
+|----------------|---------------------|------|
+| `agent.isChatting = true` | `Streaming` | 流式响应中 |
+| `agent.isChatting = false` | `Complete` | 响应完成 |
+| 消息 `status = 'error'` | `Error` | 发生错误 |
+| 消息 `status = 'stop'` | `Stop` | 用户停止 |
+
+## AGUIProtocol 事件系统
+
+### 生命周期钩子
+
+```typescript
+const protocol = new AGUIProtocol({
+  onStart: () => { /* 流式开始 */ },
+  onMessage: (event) => { /* 每个事件 */ },
+  onDone: () => { /* 流式完成 */ },
+  onError: (error) => { /* 发生错误 */ },
+});
+```
+
+### 核心事件类型
+
+| 事件 | 说明 | 使用场景 |
+|------|------|----------|
+| `TextMessageStart/Chunk/End` | 文本消息流式传输 | 实时显示 AI 回复 |
+| `ThinkingStart/End` | 思考过程 | 显示推理步骤 |
+| `ToolCallStart/Args/Result/End` | 工具调用 | 展示工具执行 |
+| `RunError` | 运行错误 | 错误处理 |
+| `MessagesSnapshot` | 消息快照 | 多端同步 |
+
+### 自定义 Protocol
+
+```typescript
+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);
+  }
+}
+```
+
+## 常用配置模式
+
+### 动态请求配置
+
+```typescript
+useChatHelper({
+  requestData: {
+    urlPrefix: '/api/',
+    // 动态 headers
+    headers: () => ({
+      Authorization: `Bearer ${localStorage.getItem('token')}`,
+      'X-Request-ID': crypto.randomUUID(),
+    }),
+    // 动态 data
+    data: () => ({
+      app_id: getCurrentAppId(),
+      tenant_id: getTenantId(),
+    }),
+  },
+});
+```
+
+### 请求/响应拦截器
+
+```typescript
+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;
+    },
+  },
+});
+```
+
+### 自定义聊天参数
+
+```typescript
+// 带额外参数发送
+agent.chat(userInput, sessionCode, 'custom_chat/', {
+  data: {
+    temperature: 0.7,
+    max_tokens: 2000,
+    model: 'gpt-4',
+  },
+  headers: {
+    'X-Chat-Mode': 'creative',
+  },
+});
+```
+
+## 消息类型
+
+### MessageRole 枚举
+
+```typescript
+enum MessageRole {
+  User = 'user',           // 用户消息
+  Assistant = 'assistant', // AI 助手
+  Reasoning = 'reasoning', // 推理过程
+  Tool = 'tool',           // 工具调用结果
+  Activity = 'activity',   // 活动（如引用文档）
+  System = 'system',       // 系统消息
+  Info = 'info',           // 信息提示
+  // ... 更多角色
+}
+```
+
+### MessageStatus 枚举
+
+```typescript
+enum MessageStatus {
+  Pending = 'pending',     // 等待中
+  Streaming = 'streaming', // 流式传输
+  Complete = 'complete',   // 完成
+  Error = 'error',         // 错误
+  Stop = 'stop',           // 已停止
+}
+```
+
+## 最佳实践
+
+### 1. 组件卸载时清理
+
+```typescript
+onUnmounted(() => {
+  agent.stopChat();
+});
+```
+
+### 2. 使用 chooseSession 切换会话
+
+```typescript
+// ✅ 推荐：自动停止聊天、加载消息
+await session.chooseSession(sessionCode);
+
+// ❌ 不推荐：手动操作
+agent.stopChat();
+session.current.value = ...;
+message.getMessages(sessionCode);
+```
+
+### 3. 枚举而非字符串
+
+```typescript
+import { MessageStatus, MessageRole } from '@blueking/chat-helper';
+
+// ✅ 推荐
+if (msg.status === MessageStatus.Streaming) { }
+
+// ❌ 不推荐
+if (msg.status === 'streaming') { }
+```
+
+### 4. Protocol 钩子快速返回
+
+```typescript
+// ✅ 推荐：不阻塞
+onMessage: (event) => {
+  console.log(event);
+  asyncOperation(); // 不 await
+}
+
+// ❌ 不推荐：阻塞
+onMessage: async (event) => {
+  await someAsyncOperation(); // 阻塞
+}
+```
+
+## 更多资源
+
+- API 详细参考: [references/api-reference.md](references/api-reference.md)
+- 完整示例代码: [references/examples.md](references/examples.md)
+- 与 chat-x 集成: [references/integration-guide.md](references/integration-guide.md)
+- chat-x UI 组件: 参考 `bk-chat-x` skill