agent-configs 1.0.0

package/skills/bk-chat-helper/references/examples.md

@@ -0,0 +1,789 @@
+# 完整示例代码
+
+## 基础聊天应用
+
+```vue
+<template>
+  <div class="chat-app">
+    <!-- 会话列表侧边栏 -->
+    <aside class="session-sidebar">
+      <button @click="createNewSession" :disabled="session.isCreateLoading.value">
+        {{ session.isCreateLoading.value ? '创建中...' : '新建会话' }}
+      </button>
+      
+      <div v-if="session.isListLoading.value" class="loading">加载中...</div>
+      <ul v-else class="session-list">
+        <li
+          v-for="item in session.list.value"
+          :key="item.sessionCode"
+          :class="{ active: session.current.value?.sessionCode === item.sessionCode }"
+          @click="session.chooseSession(item.sessionCode)"
+        >
+          <span class="name">{{ item.sessionName }}</span>
+          <button @click.stop="session.deleteSession(item.sessionCode)">删除</button>
+        </li>
+      </ul>
+    </aside>
+
+    <!-- 聊天主区域 -->
+    <main class="chat-main">
+      <!-- Agent 信息 -->
+      <header v-if="agent.info.value" class="agent-header">
+        <h2>{{ agent.info.value.agentName }}</h2>
+        <p v-if="agent.info.value.conversationSettings?.openingRemark">
+          {{ agent.info.value.conversationSettings.openingRemark }}
+        </p>
+      </header>
+
+      <!-- 消息列表 -->
+      <div v-if="message.isListLoading.value" class="loading">加载消息...</div>
+      <div v-else class="message-list">
+        <div
+          v-for="msg in message.list.value"
+          :key="msg.messageId || msg.id"
+          :class="['message', msg.role]"
+        >
+          <div class="role">{{ msg.role }}</div>
+          <div class="content">
+            <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 }}
+              <div v-if="msg.toolCalls?.length" class="tool-calls">
+                <div v-for="call in msg.toolCalls" :key="call.id" class="tool-call">
+                  调用工具: {{ call.function.name }}
+                </div>
+              </div>
+            </template>
+            <template v-else-if="msg.role === 'reasoning'">
+              <div v-for="(step, idx) in msg.content" :key="idx" class="thinking-step">
+                {{ step }}
+              </div>
+              <span v-if="msg.duration" class="duration">耗时: {{ msg.duration }}ms</span>
+            </template>
+            <template v-else-if="msg.role === 'tool'">
+              <div class="tool-result">{{ msg.content }}</div>
+              <span v-if="msg.duration" class="duration">耗时: {{ msg.duration }}ms</span>
+            </template>
+            <template v-else>
+              {{ msg.content }}
+            </template>
+          </div>
+          <div v-if="msg.status === 'streaming'" class="streaming-indicator">●</div>
+        </div>
+      </div>
+
+      <!-- 输入区域 -->
+      <div class="input-area">
+        <textarea
+          v-model="userInput"
+          @keydown.enter.prevent="handleSend"
+          placeholder="输入消息，按 Enter 发送..."
+          :disabled="agent.isChatting.value"
+        />
+        <button @click="handleSend" :disabled="!canSend">
+          {{ agent.isChatting.value ? '发送中...' : '发送' }}
+        </button>
+        <button @click="agent.stopChat()" :disabled="!agent.isChatting.value">
+          停止
+        </button>
+      </div>
+    </main>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted, onUnmounted } from 'vue';
+import { useChatHelper, AGUIProtocol } from '@blueking/chat-helper';
+
+// 用户输入
+const userInput = ref('');
+
+// 创建 chatHelper
+const chatHelper = useChatHelper({
+  requestData: {
+    urlPrefix: 'https://your-api.com/api/',
+    headers: () => ({
+      Authorization: `Bearer ${localStorage.getItem('token')}`,
+    }),
+  },
+  protocol: new AGUIProtocol({
+    onStart: () => console.log('开始响应'),
+    onDone: () => console.log('响应完成'),
+    onError: (error) => {
+      console.error('错误:', error);
+      alert('发生错误，请重试');
+    },
+  }),
+});
+
+const { agent, session, message } = chatHelper;
+
+// 能否发送
+const canSend = computed(() => 
+  !agent.isChatting.value && 
+  userInput.value.trim() && 
+  session.current.value?.sessionCode
+);
+
+// 初始化
+onMounted(async () => {
+  try {
+    await agent.getAgentInfo();
+    await session.getSessions();
+    if (session.list.value.length > 0) {
+      await session.chooseSession(session.list.value[0].sessionCode);
+    }
+  } catch (error) {
+    console.error('初始化失败:', error);
+  }
+});
+
+// 清理
+onUnmounted(() => {
+  agent.stopChat();
+});
+
+// 发送消息
+const handleSend = async () => {
+  if (!canSend.value) return;
+  
+  const input = userInput.value.trim();
+  userInput.value = '';
+  
+  await agent.chat(input, session.current.value!.sessionCode);
+};
+
+// 创建新会话
+const createNewSession = async () => {
+  await session.createSession({
+    sessionCode: `session_${Date.now()}`,
+    sessionName: `会话 ${new Date().toLocaleString()}`,
+  });
+};
+</script>
+
+<style scoped>
+.chat-app {
+  display: flex;
+  height: 100vh;
+}
+
+.session-sidebar {
+  width: 250px;
+  border-right: 1px solid #ddd;
+  padding: 16px;
+}
+
+.session-list {
+  list-style: none;
+  padding: 0;
+}
+
+.session-list li {
+  padding: 8px;
+  cursor: pointer;
+  border-radius: 4px;
+  display: flex;
+  justify-content: space-between;
+}
+
+.session-list li.active {
+  background: #e3f2fd;
+}
+
+.chat-main {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  padding: 16px;
+}
+
+.message-list {
+  flex: 1;
+  overflow-y: auto;
+}
+
+.message {
+  margin-bottom: 16px;
+  padding: 12px;
+  border-radius: 8px;
+}
+
+.message.user {
+  background: #e3f2fd;
+  margin-left: 20%;
+}
+
+.message.assistant {
+  background: #f5f5f5;
+  margin-right: 20%;
+}
+
+.message.reasoning {
+  background: #fff3e0;
+  font-size: 0.9em;
+}
+
+.message.tool {
+  background: #e8f5e9;
+  font-family: monospace;
+}
+
+.input-area {
+  display: flex;
+  gap: 8px;
+  padding-top: 16px;
+  border-top: 1px solid #ddd;
+}
+
+.input-area textarea {
+  flex: 1;
+  resize: none;
+  padding: 8px;
+}
+
+.streaming-indicator {
+  color: #2196f3;
+  animation: blink 1s infinite;
+}
+
+@keyframes blink {
+  50% { opacity: 0; }
+}
+</style>
+```
+
+---
+
+## 与 chat-x 组件完整集成
+
+```vue
+<template>
+  <div class="chat-page">
+    <!-- 预设问题（空消息时显示） -->
+    <ShortcutBtns
+      v-if="message.list.value.length === 0 && predefinedQuestions.length > 0"
+      :shortcuts="predefinedQuestions.map((q, i) => ({ id: String(i), name: q }))"
+      @select-shortcut="handleQuestionClick"
+    />
+    
+    <!-- 消息容器 -->
+    <MessageContainer
+      v-else
+      v-model:selected-messages="selectedMessages"
+      :messages="message.list.value"
+      :message-status="messageStatus"
+      :enable-selection="enableSelection"
+      :on-agent-action="handleAgentAction"
+      :on-user-action="handleUserAction"
+      @stop-streaming="handleStop"
+    />
+    
+    <!-- 快捷指令表单 -->
+    <ShortcutRender
+      v-if="selectedShortcut?.components?.length"
+      :name="selectedShortcut.name"
+      :components="selectedShortcut.components"
+      :form-model="selectedShortcut.formModel"
+      @close="selectedShortcut = null"
+      @submit="handleShortcutSubmit"
+    />
+    
+    <!-- 输入框 -->
+    <ChatInput
+      v-else
+      v-model="userInput"
+      v-model:cite="citeContent"
+      :message-status="messageStatus"
+      :placeholder="placeholder"
+      :prompts="prompts"
+      :resources="resources"
+      :shortcuts="shortcuts"
+      :shortcut-id="selectedShortcut?.id"
+      :on-send-message="handleSend"
+      :on-stop-sending="handleStop"
+      @select-shortcut="handleSelectShortcut"
+      @delete-shortcut="selectedShortcut = null"
+    />
+    
+    <!-- 划词选择 -->
+    <AiSelection
+      v-model:visible="aiSelectionVisible"
+      :shortcuts="shortcuts"
+      @select-shortcut="handleSelectShortcut"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted, onUnmounted } from 'vue';
+import {
+  ChatInput,
+  MessageContainer,
+  ShortcutBtns,
+  ShortcutRender,
+  AiSelection,
+  MessageStatus,
+  type Shortcut,
+  type IToolBtn,
+} from '@blueking/chat-x';
+import { useChatHelper, AGUIProtocol, MessageRole } from '@blueking/chat-helper';
+
+// 状态
+const userInput = ref('');
+const citeContent = ref('');
+const selectedShortcut = ref<Shortcut | null>(null);
+const selectedMessages = ref([]);
+const enableSelection = ref(false);
+const aiSelectionVisible = ref(false);
+const isStreaming = ref(false);
+
+// 配置
+const placeholder = ref('请输入消息...');
+const prompts = ref(['帮我写一篇文章', '解释这段代码']);
+const resources = ref([
+  { id: 'file', name: '上传文件', type: 'file' },
+  { id: 'image', name: '上传图片', type: 'image' },
+]);
+const shortcuts = ref<Shortcut[]>([
+  { id: 'ask', name: '问问小鲸' },
+  { id: 'translate', name: '翻译' },
+  { id: 'explain', name: '解释' },
+]);
+
+// chatHelper
+const chatHelper = useChatHelper({
+  requestData: {
+    urlPrefix: '/api/',
+    headers: () => ({
+      Authorization: `Bearer ${getToken()}`,
+    }),
+  },
+  protocol: new AGUIProtocol({
+    onStart: () => { isStreaming.value = true; },
+    onDone: () => { isStreaming.value = false; },
+    onError: (error) => {
+      isStreaming.value = false;
+      showError(error.message);
+    },
+  }),
+});
+
+const { agent, session, message } = chatHelper;
+
+// 计算属性
+const messageStatus = computed(() =>
+  isStreaming.value ? MessageStatus.Streaming : MessageStatus.Complete
+);
+
+const predefinedQuestions = computed(() =>
+  agent.info.value?.conversationSettings?.predefinedQuestions || []
+);
+
+// 初始化
+onMounted(async () => {
+  await agent.getAgentInfo();
+  await session.getSessions();
+  
+  if (session.list.value.length > 0) {
+    await session.chooseSession(session.list.value[0].sessionCode);
+  } else {
+    // 没有会话则创建一个
+    await session.createSession({
+      sessionCode: `session_${Date.now()}`,
+      sessionName: '新会话',
+    });
+  }
+});
+
+onUnmounted(() => {
+  agent.stopChat();
+});
+
+// 发送消息
+const handleSend = async (value: string) => {
+  if (!session.current.value?.sessionCode || !value.trim()) return;
+  
+  // 清空输入
+  userInput.value = '';
+  
+  // 构建消息属性
+  const property = citeContent.value
+    ? { extra: { cite: citeContent.value } }
+    : undefined;
+  citeContent.value = '';
+  
+  // 发送
+  await agent.chat(
+    value,
+    session.current.value.sessionCode,
+    undefined,
+    undefined,
+    property
+  );
+};
+
+// 停止
+const handleStop = () => {
+  agent.stopChat();
+};
+
+// 预设问题点击
+const handleQuestionClick = (shortcut: Shortcut) => {
+  userInput.value = shortcut.name;
+  handleSend(shortcut.name);
+};
+
+// 快捷指令选择
+const handleSelectShortcut = (shortcut: Shortcut, text?: string) => {
+  selectedShortcut.value = shortcut;
+  if (text) {
+    userInput.value = text;
+  }
+};
+
+// 快捷指令表单提交
+const handleShortcutSubmit = (formModel: Record<string, unknown>) => {
+  // 根据快捷指令构建消息
+  const command = selectedShortcut.value?.id;
+  const content = formModel.content as string || userInput.value;
+  
+  selectedShortcut.value = null;
+  
+  agent.chat(
+    content,
+    session.current.value!.sessionCode,
+    undefined,
+    undefined,
+    { extra: { command, ...formModel } }
+  );
+};
+
+// AI 消息操作
+const handleAgentAction = async (tool: IToolBtn) => {
+  switch (tool.id) {
+    case 'copy':
+      // 复制由组件内部处理
+      break;
+    case 'like':
+      // 返回点赞原因
+      return await session.getSessionFeedbackReasons(1) || ['回答准确', '信息全面'];
+    case 'unlike':
+      // 返回点踩原因
+      return await session.getSessionFeedbackReasons(-1) || ['信息错误', '回答不相关'];
+    case 'rebuild':
+      // 重新生成
+      const lastUserMsg = message.list.value.findLast(m => m.role === MessageRole.User);
+      if (lastUserMsg) {
+        const content = typeof lastUserMsg.content === 'string'
+          ? lastUserMsg.content
+          : JSON.stringify(lastUserMsg.content);
+        await agent.chat(content, session.current.value!.sessionCode);
+      }
+      break;
+  }
+};
+
+// 用户消息操作
+const handleUserAction = async (tool: IToolBtn, msgData: any) => {
+  switch (tool.id) {
+    case 'edit':
+      userInput.value = typeof msgData.content === 'string'
+        ? msgData.content
+        : '';
+      break;
+    case 'delete':
+      await message.deleteMessages([msgData]);
+      break;
+  }
+};
+
+// 辅助函数
+function getToken() {
+  return localStorage.getItem('token') || '';
+}
+
+function showError(msg: string) {
+  console.error(msg);
+  // 显示错误提示
+}
+</script>
+
+<style scoped>
+.chat-page {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  padding: 16px;
+}
+</style>
+```
+
+---
+
+## 自定义 Protocol 示例
+
+```typescript
+import {
+  AGUIProtocol,
+  type ITextMessageChunkEvent,
+  type IThinkingStartEvent,
+  type IToolCallStartEvent,
+  type IRunErrorEvent,
+} from '@blueking/chat-helper';
+
+class EnhancedProtocol extends AGUIProtocol {
+  private analytics: Analytics;
+  private audioPlayer: AudioPlayer;
+  
+  constructor(options?: any) {
+    super(options);
+    this.analytics = new Analytics();
+    this.audioPlayer = new AudioPlayer();
+  }
+  
+  // 文本消息 - 实时语音播报
+  handleTextMessageChunkEvent(event: ITextMessageChunkEvent) {
+    // 语音播报
+    if (this.audioPlayer.isEnabled()) {
+      this.audioPlayer.speak(event.delta || '');
+    }
+    
+    // 记录统计
+    this.analytics.trackTextChunk(event.messageId);
+    
+    // 调用父类
+    super.handleTextMessageChunkEvent(event);
+  }
+  
+  // 思考开始 - 显示动画
+  handleThinkingStartEvent(event: IThinkingStartEvent) {
+    showThinkingAnimation(event.title);
+    super.handleThinkingStartEvent(event);
+  }
+  
+  // 思考结束 - 统计时间
+  handleThinkingEndEvent(event: any) {
+    hideThinkingAnimation();
+    this.analytics.trackThinkingTime(event.duration);
+    super.handleThinkingEndEvent(event);
+  }
+  
+  // 工具调用 - 显示通知
+  handleToolCallStartEvent(event: IToolCallStartEvent) {
+    showNotification(`正在调用工具: ${event.toolCallName}`);
+    this.analytics.trackToolUsage(event.toolCallName);
+    super.handleToolCallStartEvent(event);
+  }
+  
+  // 错误处理 - 上报
+  handleRunErrorEvent(event: IRunErrorEvent) {
+    // 上报错误
+    this.analytics.reportError({
+      code: event.code,
+      message: event.message,
+      timestamp: Date.now(),
+    });
+    
+    // 显示友好提示
+    showErrorToast(event.message);
+    
+    super.handleRunErrorEvent(event);
+  }
+}
+
+// 使用
+const chatHelper = useChatHelper({
+  requestData: { urlPrefix: '/api/' },
+  protocol: new EnhancedProtocol({
+    onStart: () => showLoadingOverlay(),
+    onDone: () => hideLoadingOverlay(),
+  }),
+});
+```
+
+---
+
+## 多租户/多应用场景
+
+```typescript
+import { ref, watch } from 'vue';
+import { useChatHelper, AGUIProtocol } from '@blueking/chat-helper';
+
+// 当前应用和租户
+const currentApp = ref('app-1');
+const currentTenant = ref('tenant-1');
+
+// 创建 chatHelper
+const chatHelper = useChatHelper({
+  requestData: {
+    urlPrefix: '/api/',
+    // 动态获取
+    data: () => ({
+      app_id: currentApp.value,
+      tenant_id: currentTenant.value,
+    }),
+    headers: () => ({
+      Authorization: `Bearer ${getToken()}`,
+      'X-App-ID': currentApp.value,
+      'X-Tenant-ID': currentTenant.value,
+    }),
+  },
+});
+
+// 切换应用时重置
+watch([currentApp, currentTenant], async () => {
+  // 停止当前聊天
+  chatHelper.agent.stopChat();
+  
+  // 重新加载数据
+  await chatHelper.session.getSessions();
+  if (chatHelper.session.list.value.length > 0) {
+    await chatHelper.session.chooseSession(
+      chatHelper.session.list.value[0].sessionCode
+    );
+  }
+});
+```
+
+---
+
+## 消息本地缓存
+
+```typescript
+import { watch } from 'vue';
+import { useChatHelper } from '@blueking/chat-helper';
+
+const chatHelper = useChatHelper({
+  requestData: { urlPrefix: '/api/' },
+});
+
+const { session, message } = chatHelper;
+
+// 缓存 key
+const getCacheKey = (sessionCode: string) => `messages_${sessionCode}`;
+
+// 监听消息变化并缓存
+watch(
+  () => message.list.value,
+  (newList) => {
+    if (session.current.value?.sessionCode) {
+      localStorage.setItem(
+        getCacheKey(session.current.value.sessionCode),
+        JSON.stringify(newList)
+      );
+    }
+  },
+  { deep: true }
+);
+
+// 加载缓存
+const loadCachedMessages = (sessionCode: string) => {
+  const cached = localStorage.getItem(getCacheKey(sessionCode));
+  if (cached) {
+    try {
+      message.list.value = JSON.parse(cached);
+    } catch (e) {
+      console.error('缓存解析失败:', e);
+    }
+  }
+};
+
+// 在选择会话前先加载缓存
+const chooseSessionWithCache = async (sessionCode: string) => {
+  loadCachedMessages(sessionCode);
+  await session.chooseSession(sessionCode);
+};
+```
+
+---
+
+## 状态指示器组件
+
+```vue
+<template>
+  <div v-if="status" class="status-bar" :class="status.type">
+    <span class="icon">{{ statusIcon }}</span>
+    <span class="message">{{ status.message }}</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import {
+  useChatHelper,
+  AGUIProtocol,
+  type IThinkingStartEvent,
+  type IToolCallStartEvent,
+} from '@blueking/chat-helper';
+
+const status = ref<{ type: string; message: string } | null>(null);
+
+const statusIcon = computed(() => {
+  switch (status.value?.type) {
+    case 'thinking': return '🤔';
+    case 'tool': return '🔧';
+    case 'streaming': return '📝';
+    case 'error': return '❌';
+    case 'success': return '✅';
+    default: return '';
+  }
+});
+
+// 自定义 Protocol
+class StatusProtocol extends AGUIProtocol {
+  handleThinkingStartEvent(event: IThinkingStartEvent) {
+    status.value = { type: 'thinking', message: `思考中: ${event.title || ''}` };
+    super.handleThinkingStartEvent(event);
+  }
+  
+  handleThinkingEndEvent(event: any) {
+    status.value = null;
+    super.handleThinkingEndEvent(event);
+  }
+  
+  handleToolCallStartEvent(event: IToolCallStartEvent) {
+    status.value = { type: 'tool', message: `调用工具: ${event.toolCallName}` };
+    super.handleToolCallStartEvent(event);
+  }
+  
+  handleToolCallEndEvent(event: any) {
+    status.value = null;
+    super.handleToolCallEndEvent(event);
+  }
+}
+
+const chatHelper = useChatHelper({
+  requestData: { urlPrefix: '/api/' },
+  protocol: new StatusProtocol({
+    onStart: () => {
+      status.value = { type: 'streaming', message: '正在生成回复...' };
+    },
+    onDone: () => {
+      status.value = { type: 'success', message: '回复完成' };
+      setTimeout(() => { status.value = null; }, 2000);
+    },
+    onError: (error) => {
+      status.value = { type: 'error', message: error.message };
+    },
+  }),
+});
+</script>
+
+<style scoped>
+.status-bar {
+  padding: 8px 16px;
+  border-radius: 4px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.status-bar.thinking { background: #e3f2fd; }
+.status-bar.tool { background: #fff3e0; }
+.status-bar.streaming { background: #e8f5e9; }
+.status-bar.error { background: #ffebee; color: #c62828; }
+.status-bar.success { background: #e8f5e9; }
+</style>
+```