@blueking/chat-x 0.0.5 → 0.0.7

package/dist/mcp/generated/docs/message-render.md

@@ -0,0 +1,329 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+MessageRender 是单条消息的渲染入口，根据 message.role 派发到 UserMessage、AssistantMessage、ReasoningMessage、 ToolMessage、ActivityMessage、InfoMessage、LoadingMessage 等。Assistant 默认通过插槽用 ContentRender 渲染正文，可被默认插槽覆盖。 无独立状态，通常由 MessageContainer 内部调用而非业务直接挂载。
+
+### 关联组件
+- **message-container** — 在 MessageContainer 中按组调用以渲染每条消息
+- **assistant-message** — role 为 assistant 时渲染 AI 回复与工具调用
+- **user-message** — role 为 user 时渲染用户消息
+
+---
+<!-- FULL DOC -->
+
+# MessageRender 消息渲染器
+
+> **层级**：分子组件 · **功能域**：消息展示
+
+统一的消息渲染入口，通过 `message.role` 字段自动派发到对应的子组件。整个渲染过程由一个 `computed` 属性完成，无额外状态。
+
+## 渲染架构
+
+```
+MessageRender
+│
+├── props.message.role
+│     │
+│     ├── 'user'       → UserMessage（转发 message + onAction / onInputConfirm /
+│     │                               onShortcutConfirm / messageToolsStatus / tippyOptions）
+│     │
+│     ├── 'assistant'  → AssistantMessage（转发 message + default slot）
+│     │                    └── default slot 默认回退到 ContentRender
+│     │
+│     ├── 'info'       → InfoMessage（转发 message）
+│     ├── 'reasoning'  → ReasoningMessage（转发 message）
+│     ├── 'tool'       → ToolMessage（转发 message）
+│     ├── 'activity'   → ActivityMessage（转发 message）
+│     ├── 'loading'    → LoadingMessage（转发 message）
+│     │
+│     └── 其他 / 未知   → null（不渲染任何内容）
+```
+
+> **重要**：`onAction`、`onInputConfirm`、`onShortcutConfirm`、`messageToolsStatus`、`tippyOptions` 这五个 prop **只转发给 `UserMessage`**。`AssistantMessage` 的工具栏由 `MessageContainer` 的 `MessageTools` 组件管理，`MessageRender` 不负责传递。
+
+## 基础用法
+
+```vue
+<template>
+  <MessageRender
+    :message="message"
+    :on-action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageRender, MessageRole, MessageStatus, type Message, type IToolBtn } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Assistant,
+    content: '你好！我是 AI 助手，有什么可以帮你的吗？',
+    status: MessageStatus.Complete,
+  };
+
+  const handleAction = async (tool: IToolBtn) => {
+    console.log('消息操作:', tool.id);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 各角色消息
+
+### 用户消息（user）
+
+`onAction`、`onInputConfirm`、`onShortcutConfirm`、`messageToolsStatus` 在此角色下生效。
+
+```vue
+<script setup lang="ts">
+  import { MessageRole, MessageStatus, type Message, type IToolBtn, type TagSchema } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.User,
+    content: '你好，请帮我解释一下什么是 Vue 3 的组合式 API',
+    status: MessageStatus.Complete,
+  };
+
+  const handleAction = async (tool: IToolBtn) => {
+    console.log('用户消息操作:', tool.id); // delete / copy 等
+  };
+  const handleInputConfirm = async (content: Message['content'], docSchema: TagSchema) => {
+    console.log('编辑确认:', content);
+  };
+  const handleShortcutConfirm = async (formModel: Record<string, unknown>) => {
+    console.log('快捷指令提交:', formModel);
+  };
+</script>
+```
+
+**渲染效果**
+
+### AI 助手消息（assistant）
+
+`message` 中的全部字段（含 `toolCalls`）直接透传给 `AssistantMessage`。
+
+```vue
+<script setup lang="ts">
+  import { MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '2',
+    messageId: '2',
+    role: MessageRole.Assistant,
+    content: `## Vue 3 组合式 API\n\n**组合式 API** 是 Vue 3 引入的一种新方式...`,
+    status: MessageStatus.Complete,
+  };
+</script>
+```
+
+**渲染效果**
+
+### 信息消息（info）
+
+`content` 为字符串或字符串数组，渲染居中虚线分隔条。
+
+### 推理消息（reasoning）
+
+`content` 为字符串数组，`duration` 为推理耗时（毫秒）。
+
+### 工具调用结果（tool）
+
+在 `MessageContainer` 中通常不独立渲染（被注入到 AssistantMessage），单独使用时如下：
+
+### 活动消息（activity）
+
+### 加载消息（loading）
+
+由 `MessageContainer` 自动注入，无需手动使用。
+
+## 消息状态
+
+### 流式输出（streaming）
+
+`status: 'streaming'` 时，`AssistantMessage` 内部展示打字光标，内容可实时追加：
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MessageRole, MessageStatus, type Message } from '@blueking/chat-x';
+
+  const message = ref<Message>({
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Assistant,
+    content: '',
+    status: MessageStatus.Streaming,
+  });
+
+  // 模拟流式输出：逐步追加内容
+  const chunks = ['正在', '为你', '生成', '答案...'];
+  let i = 0;
+  const timer = setInterval(() => {
+    if (i < chunks.length) {
+      message.value.content += chunks[i++];
+    } else {
+      message.value.status = MessageStatus.Complete;
+      clearInterval(timer);
+    }
+  }, 300);
+</script>
+```
+
+**渲染效果**
+
+### 错误状态（error）
+
+```vue
+<script setup lang="ts">
+  import { MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Assistant,
+    content: '抱歉，生成回答时发生了错误，请重试。',
+    status: MessageStatus.Error,
+  };
+</script>
+```
+
+**渲染效果**
+
+## 自定义内容渲染（default slot）
+
+`default` slot **仅对 `role: 'assistant'` 生效**，用于替换默认的 `ContentRender`。未提供 slot 时回退渲染 `<ContentRender :content="message.content" :status="message.status" />`。
+
+```vue
+<template>
+  <MessageRender
+    :message="message"
+    :on-action="handleAction"
+  >
+    <template #default="{ content, status }">
+      <!-- 完全接管内容区域渲染 -->
+      <MyMarkdownRenderer
+        :content="content"
+        :streaming="status === 'streaming'"
+      />
+    </template>
+  </MessageRender>
+</template>
+```
+
+slot 参数类型与 `AssistantMessage` 的 slot 保持一致（`Partial<AssistantMessage>`），主要使用：
+
+| 参数      | 类型            | 说明         |
+| --------- | --------------- | ------------ |
+| `content` | `string`        | 消息内容     |
+| `status`  | `MessageStatus` | 当前消息状态 |
+
+## 与 MessageContainer 配合
+
+在 `MessageContainer` 的 `default` slot 中使用，可替换默认的 `MessageRender` 渲染逻辑：
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :message-status="messageStatus"
+    :on-agent-action="handleAgentAction"
+    :on-user-action="handleUserAction"
+    @stop-streaming="handleStopStreaming"
+  >
+    <template #default="{ message, messageToolsStatus }">
+      <!-- 自定义 MessageRender 的行为 -->
+      <MessageRender
+        :message="message"
+        :message-tools-status="messageToolsStatus"
+        :on-action="handleUserAction"
+        :on-input-confirm="handleInputConfirm"
+      >
+        <template
+          v-if="message.role === 'assistant'"
+          #default="{ content, status }"
+        >
+          <MyCustomContent
+            :content="content"
+            :status="status"
+          />
+        </template>
+      </MessageRender>
+    </template>
+  </MessageContainer>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名             | 类型                                                                       | 默认值 | 说明                                              |
+| ------------------ | -------------------------------------------------------------------------- | ------ | ------------------------------------------------- |
+| message            | `Partial<Message>`                                                         | —      | **必填**，消息对象，`role` 字段决定渲染哪个子组件 |
+| messageToolsStatus | `MessageToolsStatus`                                                       | —      | 工具按钮状态；**仅转发给 `UserMessage`**          |
+| onAction           | `(tool: IToolBtn) => Promise<string[] \| void>`                            | —      | 工具操作回调；**仅转发给 `UserMessage`**          |
+| onInputConfirm     | `(content: UserMessage['content'], docSchema: TagSchema) => Promise<void>` | —      | 用户编辑确认回调；**仅转发给 `UserMessage`**      |
+| onShortcutConfirm  | `(formModel: Record<string, unknown>) => Promise<void>`                    | —      | 用户快捷指令提交回调；**仅转发给 `UserMessage`**  |
+| tippyOptions       | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | —      | 自定义 Tippy 配置；**仅转发给 `UserMessage`**     |
+
+### Slots
+
+| 插槽名  | 参数                                         | 说明                                                                    |
+| ------- | -------------------------------------------- | ----------------------------------------------------------------------- |
+| default | `{ content: string, status: MessageStatus }` | 替换 AssistantMessage 的内容区域渲染；**仅对 `role: 'assistant'` 生效** |
+
+## 消息类型映射
+
+| `MessageRole` | 渲染组件           | prop 路由                                                                                               | 说明                  |
+| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------- | --------------------- |
+| `user`        | `UserMessage`      | `message` + `onAction` + `onInputConfirm` + `onShortcutConfirm` + `messageToolsStatus` + `tippyOptions` | 用户发送的消息        |
+| `assistant`   | `AssistantMessage` | `message` + `default slot`                                                                              | AI 助手回复消息       |
+| `info`        | `InfoMessage`      | `message`                                                                                               | 系统信息 / 会话分隔符 |
+| `reasoning`   | `ReasoningMessage` | `message`                                                                                               | AI 思考过程（可折叠） |
+| `tool`        | `ToolMessage`      | `message`                                                                                               | 工具调用返回结果      |
+| `activity`    | `ActivityMessage`  | `message`                                                                                               | 知识检索 / 引用文档   |
+| `loading`     | `LoadingMessage`   | `message`（字段被忽略，组件无 Props）                                                                   | 等待响应的加载占位    |
+| 其他 / 未知   | —                  | —                                                                                                       | 返回 `null`，不渲染   |
+
+## 类型定义
+
+```typescript
+import { MessageRole, MessageStatus, MessageToolsStatus, type Message, type IToolBtn } from '@blueking/chat-x';
+
+// 消息角色
+enum MessageRole {
+  User = 'user',
+  Assistant = 'assistant',
+  Info = 'info',
+  Reasoning = 'reasoning',
+  Tool = 'tool',
+  Activity = 'activity',
+  Loading = 'loading',
+}
+
+// 消息状态
+enum MessageStatus {
+  Pending = 'pending',
+  Streaming = 'streaming',
+  Complete = 'complete',
+  Error = 'error',
+  Stop = 'stop',
+  Disabled = 'disabled',
+}
+
+// 工具按钮状态（仅转发给 UserMessage）
+enum MessageToolsStatus {
+  Disabled = 'disabled',
+  Hidden = 'hidden',
+}
+```
+
+## 关联组件
+
+- [MessageContainer](./message-container.md) — 内部按组调用以渲染每条消息
+- [AssistantMessage](./assistant-message.md) — assistant 角色派发目标
+- [UserMessage](./user-message.md) — user 角色派发目标