@blueking/chat-x 0.0.24 → 0.0.26

package/dist/mcp/generated/docs/messages.md

@@ -0,0 +1,475 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+文档说明 Message 联合类型、BaseMessage、MessageRole、MessageStatus、User/Assistant/Tool/Activity/Reasoning 等具体形态及 MessageContentType。 业务构造 messages 数组供 ChatContainer/MessageContainer 渲染；Tool 消息经 useMessageGroup 注入 Assistant。可声明合并扩展 AIBluekingMessageMap。
+
+### 关联组件
+- **message-container** — 列表渲染与工具栏
+- **message-render** — 按 role 分发渲染
+- **chat-container** — 数据源与交互入口
+
+---
+<!-- FULL DOC -->
+
+# 消息类型
+
+> **分类**：type
+
+`@blueking/chat-x` 提供了完整的消息类型定义，用于构建 AI 对话消息。
+
+## 消息基础类型
+
+### Message
+
+所有消息类型的联合类型：
+
+```typescript
+type Message = MessageMap[MessageType];
+```
+
+### BaseMessage
+
+消息基础接口：
+
+```typescript
+interface BaseMessage<T extends MessageType, C = string> {
+  // 消息唯一 ID（客户端生成）
+  id: number | string;
+
+  // 消息 ID（服务端返回）
+  messageId: number | string;
+
+  // 消息角色
+  role: T;
+
+  // 消息内容
+  content: C;
+
+  // 消息状态
+  status: MessageStatus;
+
+  // 可选：单条消息实例唯一标识（`useMessageGroup` 在缺失时会自动生成并写回）
+  uid?: string;
+
+  // 消息名称（可选）
+  name?: string;
+
+  // 消息属性（可选）
+  property?: {
+    extra?: {
+      // 引用内容
+      cite:
+        | string
+        | {
+            title: string;
+            data: { key: string; value: string }[];
+            type: 'structured';
+          };
+      // 快捷指令名称
+      command: string;
+      // 上下文信息
+      context: Record<string, any>[];
+      // 快捷指令配置
+      shortcut?: Shortcut;
+      // 暂停标记：为 true 时该消息所在消息组不显示 MessageTools 工具栏
+      pause?: boolean;
+    };
+  };
+}
+```
+
+## 消息角色
+
+```typescript
+enum MessageRole {
+  // 用户消息
+  User = 'user',
+
+  // AI 助手消息
+  Assistant = 'assistant',
+
+  // 系统消息
+  System = 'system',
+
+  // 开发者消息
+  Developer = 'developer',
+
+  // 引导消息
+  Guide = 'guide',
+
+  // 隐藏消息（不显示）
+  Hidden = 'hidden',
+  HiddenAssistant = 'hidden-assistant',
+  HiddenGuide = 'hidden-guide',
+  HiddenSystem = 'hidden-system',
+  HiddenUser = 'hidden-user',
+
+  // 信息消息
+  Info = 'info',
+
+  // 加载中消息
+  Loading = 'loading',
+
+  // 暂停消息
+  Pause = 'pause',
+
+  // 占位消息
+  Placeholder = 'placeholder',
+
+  // 推理过程消息
+  Reasoning = 'reasoning',
+
+  // 模板消息
+  TemplateAssistant = 'template-assistant',
+  TemplateGuide = 'template-guide',
+  TemplateHidden = 'template-hidden',
+  TemplateSystem = 'template-system',
+  TemplateUser = 'template-user',
+
+  // 工具调用消息
+  Tool = 'tool',
+
+  // 活动消息（如引用文档）
+  Activity = 'activity',
+}
+```
+
+## 消息状态
+
+```typescript
+enum MessageStatus {
+  // 等待中
+  Pending = 'pending',
+
+  // 流式输出中
+  Streaming = 'streaming',
+
+  // 已完成
+  Complete = 'complete',
+
+  // 错误
+  Error = 'error',
+
+  // 已停止
+  Stop = 'stop',
+
+  // 已禁用
+  Disabled = 'disabled',
+}
+```
+
+## 具体消息类型
+
+### UserMessage
+
+用户消息：
+
+```typescript
+type UserMessage = BaseMessage<MessageRole.User, InputContent[] | string>;
+
+// 示例
+const userMessage: UserMessage = {
+  id: '1',
+  messageId: 1,
+  role: MessageRole.User,
+  content: '你好',
+  status: MessageStatus.Complete,
+};
+```
+
+### AssistantMessage
+
+AI 助手消息：
+
+```typescript
+interface AssistantMessage extends BaseMessage<MessageRole.Assistant> {
+  // 工具调用列表
+  toolCalls?: ToolCall[];
+}
+
+// 工具调用
+type ToolCall = {
+  id: string;
+  type: MessageContentType.Function;
+  function: FunctionCall;
+};
+
+type FunctionCall = {
+  name: string;
+  arguments: string;
+  description?: string;
+  mcpName?: string;
+};
+
+// 示例
+const assistantMessage: AssistantMessage = {
+  id: '2',
+  messageId: 2,
+  role: MessageRole.Assistant,
+  content: '你好！有什么可以帮助你的？',
+  status: MessageStatus.Complete,
+  toolCalls: [
+    {
+      id: 'call_1',
+      type: MessageContentType.Function,
+      function: {
+        name: 'get_weather',
+        arguments: '{"city": "北京"}',
+      },
+    },
+  ],
+};
+```
+
+### ReasoningMessage
+
+推理过程消息：
+
+```typescript
+interface ReasoningMessage extends BaseMessage<MessageRole.Reasoning, string[]> {
+  // 推理耗时（毫秒）
+  duration?: number;
+}
+
+// 示例
+const reasoningMessage: ReasoningMessage = {
+  id: '3',
+  messageId: 3,
+  role: MessageRole.Reasoning,
+  content: ['让我分析一下这个问题...', '首先，需要考虑以下几点：', '1. 技术可行性'],
+  status: MessageStatus.Complete,
+  duration: 3500,
+};
+```
+
+### ToolMessage
+
+工具调用结果消息：
+
+```typescript
+interface ToolMessage extends BaseMessage<MessageRole.Tool, string> {
+  // 工具调用 ID（对应 AssistantMessage 中的 toolCalls[].id）
+  toolCallId: string;
+
+  // 执行耗时（毫秒）
+  duration: number;
+
+  // 错误信息
+  error?: string;
+}
+
+// 示例
+const toolMessage: ToolMessage = {
+  id: '4',
+  messageId: 4,
+  role: MessageRole.Tool,
+  content: '{"temperature": 25, "weather": "晴天"}',
+  status: MessageStatus.Complete,
+  toolCallId: 'call_1',
+  duration: 1200,
+};
+```
+
+### ActivityMessage
+
+活动消息（如引用文档、知识检索）：
+
+```typescript
+// 引用文档内容类型
+type ReferenceDocumentContent = {
+  name: string;
+  originFile: string;
+  url: string;
+};
+
+// 知识检索内容类型
+type KnowledgeRagContent = {
+  content: string;
+  referenceDocument: ReferenceDocumentContent[];
+};
+
+interface ActivityMessage extends BaseMessage<MessageRole.Activity, KnowledgeRagContent | ReferenceDocumentContent[]> {
+  activityType: MessageContentType.KnowledgeRag | MessageContentType.ReferenceDocument | string;
+}
+
+// 示例 1：引用文档
+const referenceMessage: ActivityMessage = {
+  id: '5',
+  messageId: 5,
+  role: MessageRole.Activity,
+  content: [
+    { name: '参考文档 1', url: 'https://example.com/1', originFile: 'https://example.com/origin/1' },
+    { name: '参考文档 2', url: 'https://example.com/2', originFile: 'https://example.com/origin/2' },
+  ],
+  status: MessageStatus.Complete,
+  activityType: 'reference',
+};
+
+// 示例 2：知识检索（knowledge_rag）
+const knowledgeRagMessage: ActivityMessage = {
+  id: '6',
+  messageId: 6,
+  role: MessageRole.Activity,
+  content: {
+    content: '开始召回知识\n重排召回结果中\n完成召回并分类\n',
+    referenceDocument: [
+      { name: '知识文档 1', url: 'https://example.com/doc1', originFile: 'https://example.com/origin/doc1' },
+      { name: '知识文档 2', url: 'https://example.com/doc2', originFile: 'https://example.com/origin/doc2' },
+    ],
+  },
+  status: MessageStatus.Complete,
+  activityType: 'knowledge_rag',
+};
+```
+
+**ActivityMessage 类型说明：**
+
+| activityType      | content 类型                 | 说明                                     |
+| ----------------- | ---------------------------- | ---------------------------------------- |
+| `'reference'`     | `ReferenceDocumentContent[]` | 引用文档列表                             |
+| `'knowledge_rag'` | `KnowledgeRagContent`        | 知识检索结果，包含检索过程内容和引用文档 |
+
+**ReferenceDocumentContent 字段说明：**
+
+| 字段         | 类型     | 说明             |
+| ------------ | -------- | ---------------- |
+| `name`       | `string` | 文档名称         |
+| `url`        | `string` | 文档预览链接     |
+| `originFile` | `string` | 文档原始文件链接 |
+
+### InfoMessage
+
+信息消息：
+
+```typescript
+type InfoMessage = BaseMessage<MessageRole.Info, string>;
+
+// 示例
+const infoMessage: InfoMessage = {
+  id: '6',
+  messageId: 6,
+  role: MessageRole.Info,
+  content: '会话已开始',
+  status: MessageStatus.Complete,
+};
+```
+
+### LoadingMessage
+
+加载中消息，用于在等待 AI 响应时显示加载状态：
+
+```typescript
+type LoadingMessage = BaseMessage<MessageRole.Loading, string>;
+
+// 示例
+const loadingMessage: LoadingMessage = {
+  id: 'loading',
+  messageId: '',
+  role: MessageRole.Loading,
+  content: '',
+  status: MessageStatus.Pending,
+};
+```
+
+## 消息内容类型
+
+```typescript
+enum MessageContentType {
+  // 二进制内容
+  Binary = 'binary',
+
+  // 函数调用
+  Function = 'function',
+
+  // 键值对
+  KeyValue = 'key-value',
+
+  // 知识检索
+  KnowledgeRag = 'knowledge-rag',
+
+  // 其他
+  Other = 'other',
+
+  // 引用文档
+  ReferenceDocument = 'reference-document',
+
+  // 文本
+  Text = 'text',
+}
+```
+
+## 类型扩展
+
+支持通过声明合并扩展消息类型：
+
+```typescript
+// 在项目中扩展
+declare global {
+  interface AIBluekingMessageMap {
+    'custom-role': CustomMessage;
+  }
+}
+
+interface CustomMessage extends BaseMessage<'custom-role'> {
+  customField: string;
+}
+```
+
+## 使用示例
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :message-status="messageStatus"
+    :on-agent-action="handleAgentAction"
+    :on-user-action="handleUserAction"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MessageContainer, MessageRole, MessageStatus, type Message } from '@blueking/chat-x';
+
+  const messageStatus = ref<MessageStatus>(MessageStatus.Complete);
+
+  const messages = ref<Message[]>([
+    {
+      id: '1',
+      messageId: 1,
+      role: MessageRole.User,
+      content: '你好',
+      status: MessageStatus.Complete,
+    },
+    {
+      id: '2',
+      messageId: 2,
+      role: MessageRole.Reasoning,
+      content: ['思考中...', '分析问题...'],
+      status: MessageStatus.Complete,
+      duration: 2000,
+    },
+    {
+      id: '3',
+      messageId: 3,
+      role: MessageRole.Assistant,
+      content: '你好！有什么可以帮助你的？',
+      status: MessageStatus.Complete,
+    },
+  ]);
+
+  const handleAgentAction = async tool => {
+    console.log('Agent action:', tool);
+  };
+
+  const handleUserAction = async tool => {
+    console.log('User action:', tool);
+  };
+</script>
+```
+
+## 关联组件
+
+- [MessageContainer](../components/molecular/message-container.md) — 消息列表
+- [MessageRender](../components/molecular/message-render.md) — 单条消息渲染
+- [ChatContainer](../components/molecular/chat-container.md) — 聊天容器