agent-configs 1.0.0

package/skills/bk-chat-helper/references/integration-guide.md

@@ -0,0 +1,583 @@
+# chat-helper 与 chat-x 集成指南
+
+本指南详细说明如何将 `@blueking/chat-helper` SDK 与 `@blueking/chat-x` UI 组件库集成，构建完整的 AI 智能体应用。
+
+## 架构概述
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      应用层 (Vue 组件)                        │
+├──────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────┐    ┌─────────────────────────────┐  │
+│  │  @blueking/chat-x   │    │  @blueking/chat-helper      │  │
+│  │  (UI 组件库)         │    │  (业务逻辑 SDK)              │  │
+│  │                     │    │                             │  │
+│  │  - ChatInput        │◄──►│  - useChatHelper()          │  │
+│  │  - MessageContainer │    │    - agent                  │  │
+│  │  - ShortcutBtns     │    │    - session                │  │
+│  │  - ShortcutRender   │    │    - message                │  │
+│  │  - AiSelection      │    │                             │  │
+│  └─────────────────────┘    └─────────────────────────────┘  │
+├──────────────────────────────────────────────────────────────┤
+│                        后端 API                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**职责划分**：
+- **chat-x**: 纯 UI 渲染，不包含业务逻辑
+- **chat-helper**: 状态管理、API 调用、流式处理
+
+---
+
+## 状态映射
+
+### MessageStatus 映射
+
+| chat-helper 状态 | chat-x MessageStatus | 触发场景 |
+|-----------------|---------------------|----------|
+| `message.status = 'pending'` | `MessageStatus.Pending` | 等待响应 |
+| `message.status = 'streaming'` | `MessageStatus.Streaming` | 流式输出中 |
+| `message.status = 'complete'` | `MessageStatus.Complete` | 响应完成 |
+| `message.status = 'error'` | `MessageStatus.Error` | 发生错误 |
+| `message.status = 'stop'` | `MessageStatus.Stop` | 用户停止 |
+| `agent.isChatting = true` | `MessageStatus.Streaming` | 正在聊天 |
+
+### 状态计算示例
+
+```typescript
+import { computed } from 'vue';
+import { MessageStatus } from '@blueking/chat-x';
+import { useChatHelper } from '@blueking/chat-helper';
+
+const { agent, message } = useChatHelper({ /* ... */ });
+
+// 方式 1：基于 agent.isChatting
+const messageStatus = computed(() =>
+  agent.isChatting.value ? MessageStatus.Streaming : MessageStatus.Complete
+);
+
+// 方式 2：基于最后一条消息状态
+const messageStatus = computed(() => {
+  const lastMsg = message.list.value.at(-1);
+  if (!lastMsg) return MessageStatus.Complete;
+  
+  switch (lastMsg.status) {
+    case 'streaming': return MessageStatus.Streaming;
+    case 'pending': return MessageStatus.Pending;
+    case 'error': return MessageStatus.Error;
+    case 'stop': return MessageStatus.Stop;
+    default: return MessageStatus.Complete;
+  }
+});
+```
+
+---
+
+## 组件对接
+
+### 1. ChatInput 对接
+
+```vue
+<template>
+  <ChatInput
+    v-model="userInput"
+    v-model:cite="citeContent"
+    :message-status="messageStatus"
+    :placeholder="placeholder"
+    :prompts="prompts"
+    :resources="resources"
+    :shortcuts="shortcuts"
+    :shortcut-id="selectedShortcutId"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+    @select-shortcut="handleSelectShortcut"
+    @delete-shortcut="handleDeleteShortcut"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { ChatInput, MessageStatus, type Shortcut, type TagSchema } from '@blueking/chat-x';
+import { useChatHelper, AGUIProtocol } from '@blueking/chat-helper';
+
+const userInput = ref<string | TagSchema>('');
+const citeContent = ref('');
+const selectedShortcutId = ref<string | null>(null);
+const isStreaming = ref(false);
+
+const chatHelper = useChatHelper({
+  requestData: { urlPrefix: '/api/' },
+  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
+);
+
+// 发送消息
+const handleSendMessage = async (value: string, docSchema: TagSchema) => {
+  if (!session.current.value?.sessionCode) return;
+  
+  // 构建消息属性
+  const property = citeContent.value
+    ? { extra: { cite: citeContent.value } }
+    : undefined;
+  
+  // 清空输入
+  userInput.value = '';
+  citeContent.value = '';
+  
+  // 发送
+  await agent.chat(
+    value,
+    session.current.value.sessionCode,
+    undefined,
+    undefined,
+    property
+  );
+};
+
+// 停止发送
+const handleStopSending = async () => {
+  agent.stopChat();
+};
+
+// 快捷指令选择
+const handleSelectShortcut = (shortcut: Shortcut, text?: string) => {
+  selectedShortcutId.value = shortcut.id;
+  if (text) userInput.value = text;
+};
+
+// 删除快捷指令
+const handleDeleteShortcut = () => {
+  selectedShortcutId.value = null;
+};
+</script>
+```
+
+### 2. MessageContainer 对接
+
+```vue
+<template>
+  <MessageContainer
+    v-model:selected-messages="selectedMessages"
+    :messages="messages"
+    :message-status="messageStatus"
+    :enable-selection="enableSelection"
+    :on-agent-action="handleAgentAction"
+    :on-user-action="handleUserAction"
+    @stop-streaming="handleStopStreaming"
+  >
+    <!-- 自定义消息渲染（可选） -->
+    <template #default="{ message: msg }">
+      <ActivityMessage v-if="msg.role === 'activity'" :message="msg" />
+      <ReasoningMessage v-else-if="msg.role === 'reasoning'" :message="msg" />
+      <MessageRender v-else :message="msg" :on-action="handleAction" />
+    </template>
+  </MessageContainer>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import {
+  MessageContainer,
+  MessageRender,
+  MessageStatus,
+  type IToolBtn,
+} from '@blueking/chat-x';
+import { useChatHelper, MessageRole } from '@blueking/chat-helper';
+
+const selectedMessages = ref([]);
+const enableSelection = ref(false);
+
+const { agent, session, message } = useChatHelper({ /* ... */ });
+
+// 消息列表直接使用 chat-helper 的数据
+const messages = computed(() => message.list.value);
+
+// AI 消息操作
+const handleAgentAction = async (tool: IToolBtn, msgData: any) => {
+  switch (tool.id) {
+    case 'copy':
+      // 复制由组件内部处理
+      break;
+    case 'like':
+      // 返回点赞原因列表
+      const likeReasons = await session.getSessionFeedbackReasons(1);
+      return likeReasons || ['回答准确', '信息全面', '解决了问题'];
+    case 'unlike':
+      // 返回点踩原因列表
+      const unlikeReasons = await session.getSessionFeedbackReasons(-1);
+      return unlikeReasons || ['信息错误', '回答不相关', '内容重复'];
+    case 'rebuild':
+      // 重新生成
+      await rebuildMessage(msgData);
+      break;
+  }
+};
+
+// 用户消息操作
+const handleUserAction = async (tool: IToolBtn, msgData: any) => {
+  switch (tool.id) {
+    case 'edit':
+      // 编辑消息
+      editMessage(msgData);
+      break;
+    case 'delete':
+      // 删除消息
+      await message.deleteMessages([msgData]);
+      break;
+  }
+};
+
+// 停止流式
+const handleStopStreaming = () => {
+  agent.stopChat();
+};
+
+// 重新生成
+const rebuildMessage = async (msgData: any) => {
+  // 找到对应的用户消息
+  const index = message.list.value.findIndex(m => m.messageId === msgData.messageId);
+  if (index > 0) {
+    const userMsg = message.list.value[index - 1];
+    if (userMsg.role === MessageRole.User) {
+      const content = typeof userMsg.content === 'string'
+        ? userMsg.content
+        : JSON.stringify(userMsg.content);
+      await agent.chat(content, session.current.value!.sessionCode);
+    }
+  }
+};
+
+const editMessage = (msgData: any) => {
+  // 实现编辑逻辑
+};
+</script>
+```
+
+### 3. ShortcutBtns + ShortcutRender 对接
+
+```vue
+<template>
+  <div class="shortcut-area">
+    <!-- 快捷指令按钮（空消息时显示） -->
+    <ShortcutBtns
+      v-if="showShortcutBtns"
+      :shortcuts="shortcuts"
+      @select-shortcut="handleSelectShortcut"
+    />
+    
+    <!-- 快捷指令表单 -->
+    <ShortcutRender
+      v-if="selectedShortcut?.components?.length"
+      :name="selectedShortcut.name"
+      :components="selectedShortcut.components"
+      :form-model="selectedShortcut.formModel"
+      @close="handleCloseShortcut"
+      @submit="handleSubmitShortcut"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { ShortcutBtns, ShortcutRender, type Shortcut } from '@blueking/chat-x';
+import { useChatHelper } from '@blueking/chat-helper';
+
+const selectedShortcut = ref<Shortcut | null>(null);
+
+const { agent, session, message } = useChatHelper({ /* ... */ });
+
+// 从 agent 信息获取快捷指令
+const shortcuts = computed<Shortcut[]>(() => {
+  const commands = agent.info.value?.conversationSettings?.commands;
+  if (!commands) return [];
+  
+  return commands.map(cmd => ({
+    id: cmd.id,
+    name: cmd.name,
+    icon: cmd.icon,
+    components: cmd.components?.map(comp => ({
+      type: comp.type,
+      key: comp.key,
+      name: comp.name,
+      props: {
+        placeholder: comp.placeholder,
+        options: comp.options,
+        rows: comp.rows,
+      },
+      fillBack: comp.fillBack,
+      required: comp.required,
+    })),
+  }));
+});
+
+// 是否显示快捷指令按钮
+const showShortcutBtns = computed(() =>
+  message.list.value.length === 0 && shortcuts.value.length > 0
+);
+
+// 选择快捷指令
+const handleSelectShortcut = (shortcut: Shortcut, text?: string) => {
+  selectedShortcut.value = {
+    ...shortcut,
+    formModel: text ? { content: text } : {},
+  };
+};
+
+// 关闭快捷指令
+const handleCloseShortcut = () => {
+  selectedShortcut.value = null;
+};
+
+// 提交快捷指令表单
+const handleSubmitShortcut = async (formModel: Record<string, unknown>) => {
+  if (!session.current.value?.sessionCode) return;
+  
+  // 构建消息内容
+  const content = (formModel.content as string) || selectedShortcut.value?.name || '';
+  
+  // 构建消息属性
+  const property = {
+    extra: {
+      command: selectedShortcut.value?.id,
+      ...formModel,
+    },
+  };
+  
+  selectedShortcut.value = null;
+  
+  // 发送
+  await agent.chat(
+    content,
+    session.current.value.sessionCode,
+    undefined,
+    undefined,
+    property
+  );
+};
+</script>
+```
+
+### 4. AiSelection 对接
+
+```vue
+<template>
+  <AiSelection
+    v-model:visible="aiSelectionVisible"
+    :shortcuts="selectionShortcuts"
+    :max-shortcut-count="3"
+    :offset="10"
+    @select-shortcut="handleSelectionShortcut"
+    @selection-change="handleSelectionChange"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { AiSelection, type Shortcut } from '@blueking/chat-x';
+import { useChatHelper } from '@blueking/chat-helper';
+
+const aiSelectionVisible = ref(false);
+const selectedText = ref('');
+
+const { agent, session } = useChatHelper({ /* ... */ });
+
+// 划词快捷指令（通常是子集）
+const selectionShortcuts = computed<Shortcut[]>(() => [
+  { id: 'ask', name: '问问小鲸' },
+  { id: 'translate', name: '翻译' },
+  { id: 'explain', name: '解释' },
+]);
+
+// 选区变化
+const handleSelectionChange = (text: string) => {
+  selectedText.value = text;
+};
+
+// 选择快捷指令
+const handleSelectionShortcut = async (shortcut: Shortcut, text: string) => {
+  if (!session.current.value?.sessionCode) return;
+  
+  // 根据快捷指令构建内容
+  let content = text;
+  if (shortcut.id === 'translate') {
+    content = `翻译以下内容：\n${text}`;
+  } else if (shortcut.id === 'explain') {
+    content = `解释以下内容：\n${text}`;
+  }
+  
+  // 发送
+  await agent.chat(
+    content,
+    session.current.value.sessionCode,
+    undefined,
+    undefined,
+    { extra: { command: shortcut.id, cite: text } }
+  );
+};
+</script>
+```
+
+---
+
+## 数据流转示例
+
+### 完整对话流程
+
+```
+1. 用户输入 → ChatInput.onSendMessage
+2. 调用 agent.chat(userInput, sessionCode)
+   ├─ 创建用户消息 → message.list 更新
+   └─ 发起 SSE 请求
+3. Protocol.onStart → isStreaming = true → MessageStatus.Streaming
+4. 流式事件处理：
+   ├─ TextMessageStart → 创建 AI 消息占位
+   ├─ TextMessageChunk → 更新 AI 消息内容
+   ├─ ThinkingStart → 创建推理消息
+   ├─ ToolCallStart → 创建工具调用消息
+   └─ TextMessageEnd → 标记消息完成
+5. Protocol.onDone → isStreaming = false → MessageStatus.Complete
+6. MessageContainer 自动更新渲染
+```
+
+### 会话切换流程
+
+```
+1. 用户点击会话 → session.chooseSession(sessionCode)
+   ├─ agent.stopChat() → 停止当前聊天
+   ├─ session.current = 目标会话
+   ├─ message.getMessages(sessionCode) → 加载消息
+   └─ agent.resumeStreamingChat() → 恢复流式（如果需要）
+2. MessageContainer 更新显示新会话消息
+3. ChatInput 清空输入状态
+```
+
+---
+
+## 错误处理
+
+### 统一错误处理
+
+```typescript
+import { useChatHelper, AGUIProtocol } from '@blueking/chat-helper';
+import { Message } from 'bkui-vue';
+
+const chatHelper = useChatHelper({
+  requestData: { urlPrefix: '/api/' },
+  interceptors: {
+    response: (response) => {
+      // API 业务错误
+      if (response.data.code !== 0) {
+        Message({ theme: 'error', message: response.data.message });
+      }
+      return response;
+    },
+  },
+  protocol: new AGUIProtocol({
+    onError: (error) => {
+      // 流式错误
+      Message({ theme: 'error', message: `AI 响应错误: ${error.message}` });
+    },
+  }),
+});
+```
+
+### 重试机制
+
+```typescript
+const retryChat = async (retries = 3) => {
+  for (let i = 0; i < retries; i++) {
+    try {
+      await agent.chat(userInput, sessionCode);
+      return; // 成功则退出
+    } catch (error) {
+      if (i === retries - 1) {
+        throw error; // 最后一次仍失败则抛出
+      }
+      await new Promise(r => setTimeout(r, 1000 * (i + 1))); // 递增延迟
+    }
+  }
+};
+```
+
+---
+
+## 性能优化
+
+### 1. 消息虚拟滚动
+
+对于大量消息，使用虚拟滚动：
+
+```vue
+<template>
+  <VirtualScroll
+    :items="message.list.value"
+    :item-height="80"
+    v-slot="{ item }"
+  >
+    <MessageRender :message="item" />
+  </VirtualScroll>
+</template>
+```
+
+### 2. 防抖发送
+
+```typescript
+import { useDebounceFn } from '@vueuse/core';
+
+const debouncedSend = useDebounceFn((value: string) => {
+  agent.chat(value, session.current.value!.sessionCode);
+}, 300);
+```
+
+### 3. 消息分页加载
+
+```typescript
+const loadMoreMessages = async () => {
+  if (message.isListLoading.value) return;
+  
+  // 获取更早的消息
+  const oldestMsg = message.list.value[0];
+  if (oldestMsg?.messageId) {
+    await message.getMessages(sessionCode, { before: oldestMsg.messageId });
+  }
+};
+```
+
+---
+
+## 最佳实践检查清单
+
+### 初始化
+- [ ] `onMounted` 中初始化 agent 和 session
+- [ ] 有会话则选择第一个，无则创建
+- [ ] 处理初始化错误
+
+### 清理
+- [ ] `onUnmounted` 中调用 `agent.stopChat()`
+- [ ] 清理定时器和事件监听
+
+### 状态管理
+- [ ] 使用 computed 映射 messageStatus
+- [ ] 正确处理 loading 状态
+- [ ] 使用枚举而非字符串
+
+### 错误处理
+- [ ] 配置拦截器处理 API 错误
+- [ ] 配置 Protocol.onError 处理流式错误
+- [ ] 提供友好的错误提示
+
+### 用户体验
+- [ ] 发送后清空输入框
+- [ ] 流式响应时禁用发送按钮
+- [ ] 提供停止按钮
+- [ ] 自动滚动到最新消息