@blueking/chat-x 0.0.48-beta.1 → 0.0.49-beta.10

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

@@ -1,12 +1,13 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-消息悬浮工具栏，组合复制、删除、反馈等工具按钮。 源码位置：src/components/message-tools/message-tools.vue。
+消息悬浮工具栏，组合复制、删除、反馈等工具按钮；提供 prepend / append 两端插槽承载消息时间等附加内容。 源码位置：src/components/message-tools/message-tools.vue。
 
 ### 关联组件
 - **tool-btn** — 普通工具项由 ToolBtn 渲染
 - **user-feedback** — like/unlike 时弹出反馈表单
 - **delete-tool** — id 为 delete 时替换为带确认的删除按钮
+- **message-time** — 通过 prepend / append 插槽嵌入消息时间
 
 ---
 <!-- FULL DOC -->
@@ -20,22 +21,22 @@
 
 > **能力域**：工具与反馈
 
-AI 消息的操作工具栏组件，由**左侧消息工具区**和**右侧更新工具区**两部分组成，中间以分隔线分隔。仅 `like` / `unlike` 按钮会弹出反馈表单（`UserFeedback`），其余按钮直接触发 `onAction`。
+AI 消息的操作工具栏组件，由**左侧消息工具区**和**右侧更新工具区**两部分组成，中间以分隔线分隔；两端另有 `prepend` / `append` 插槽用于挂载消息时间等附加内容。仅 `like` / `unlike` 按钮会弹出反馈表单（`UserFeedback`），其余按钮直接触发 `onAction`。
 
 ## 组件结构
 
 ```
-┌─────────────────────────────────────────────────────┐
-│  .ai-message-tools-container                           │
-│  ┌─────────────────────┐  │  ┌───────────────────┐ │
-│  │  messageTools        │  │  │  updateTools      │ │
-│  │  copy cite rebuild…  │  │  │  like unlike del  │ │
-│  └─────────────────────┘  │  └───────────────────┘ │
-│             左侧区域      分隔线   右侧区域          │
-└─────────────────────────────────────────────────────┘
+┌───────────────────────────────────────────────────────────────────────┐
+│  .ai-message-tools-container（display: flex，gap: 4px）                 │
+│  ┌────────┐  ┌─────────────────────┐  │  ┌───────────────┐  ┌───────┐ │
+│  │#prepend│  │  messageTools        │  │  │  updateTools  │  │#append│ │
+│  │        │  │  copy cite rebuild…  │  │  │ like unlike…  │  │       │ │
+│  └────────┘  └─────────────────────┘  │  └───────────────┘  └───────┘ │
+│    插槽区          左侧区域         分隔线    右侧区域          插槽区   │
+└───────────────────────────────────────────────────────────────────────┘
 ```
 
-- 分隔线（`.ai-divider`）仅在 `updateTools` 非空时显示
+- 分隔线（`.ai-divider`）与**右侧更新工具区**均仅在 `updateTools` 非空时渲染
 - `updateTools` 中 `id` 为 `like` / `unlike` 的按钮被 `Tippy` 弹窗包裹，点击后展示 `UserFeedback` 反馈表单
 - `updateTools` 中 `id` 为 `delete` 的按钮使用 `DeleteTool` 组件，点击后展示**确认删除弹窗**（含"删除"/"取消"按钮），确认后触发 `onAction`
 - `updateTools` 中其他按钮直接触发 `onAction`，不弹表单
@@ -224,6 +225,32 @@ const CONST_UPDATE_TOOLS = [
 
 **渲染效果**
 
+## 两端插槽（prepend / append）
+
+`prepend`（工具图标左侧）与 `append`（工具图标右侧）用于在工具栏两端挂载附加内容，项目内用于放置 [MessageTime 消息时间](/components/feedback/message-time)：
+
+| 场景      | 使用插槽  | 效果                                    |
+| --------- | --------- | --------------------------------------- |
+| 用户消息  | `prepend` | 时间显示在工具图标左侧                  |
+| AI 消息组 | `append`  | 时间显示在工具图标右侧                  |
+
+```vue
+<template>
+  <MessageTools :on-action="handleAction">
+    <template #append>
+      <MessageTime :created-at="createdAt" />
+    </template>
+  </MessageTools>
+</template>
+
+<script setup lang="ts">
+  import { MessageTime, MessageTools } from '@blueking/chat-x';
+</script>
+```
+
+- 插槽包裹容器（`.ai-message-tools-prepend` / `.ai-message-tools-append`）仅在对应插槽传入时渲染
+- 插槽内容为空时（如消息无 `createdAt`，`MessageTime` 不渲染任何 DOM），包裹容器命中 `:empty` 被收起，不会留下多余间距
+
 ## 工具栏状态控制
 
 `messageToolsStatus` 控制工具栏整体状态：
@@ -357,6 +384,13 @@ const CONST_UPDATE_TOOLS = [
 | -------- | ------------------------------------------------------------- | ------------------------------------------ |
 | feedback | `(tool: IToolBtn, reasonList: string[], otherReason: string)` | 用户在反馈表单点击"提交"后触发（not 取消） |
 
+### Slots
+
+| 插槽名  | 作用域参数 | 说明                                             |
+| ------- | ---------- | ------------------------------------------------ |
+| prepend | —          | 工具图标左侧的附加内容，如用户消息的时间         |
+| append  | —          | 工具图标右侧的附加内容，如 AI 消息组的时间       |
+
 ## 类型定义
 
 ```typescript
@@ -382,4 +416,5 @@ enum MessageToolsStatus {
 
 - [ToolBtn](/components/feedback/tool-btn) — 单项工具按钮
 - [UserFeedback](/components/feedback/user-feedback) — 点赞/踩反馈面板
-- [DeleteTool](/components/feedback/delete-tool) — 删除二次确认
+- [DeleteTool](/components/feedback/delete-tool) — 删除二次确认
+- [MessageTime](/components/feedback/message-time) — 两端插槽内的消息时间

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

@@ -54,6 +54,10 @@ interface BaseMessage<T extends MessageType, C = string> {
   // 消息名称（可选）
   name?: string;
 
+  // 可选：消息创建时间，ISO 字符串或毫秒时间戳，由消息层（chat-helper）写入
+  // 用于 MessageTime 展示；缺省时不展示时间
+  createdAt?: number | string;
+
   // 消息属性（可选）
   property?: {
     extra?: {
@@ -144,6 +148,9 @@ enum MessageStatus {
   // 已完成
   Complete = 'complete',
 
+  // 已完成（与 Complete 同义，兼容协议/后端返回的 completed）
+  Completed = 'completed',
+
   // 已禁用
   Disabled = 'disabled',
 
@@ -170,6 +177,8 @@ enum MessageStatus {
 }
 ```
 
+完整取值与说明见 [常量枚举 · MessageStatus](./constants#messagestatus)。
+
 ## 具体消息类型
 
 ### UserMessage

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

@@ -12,13 +12,14 @@
 <!-- FULL DOC -->
 
 # ReasoningMessage 推理消息
+
 ## 源码事实
 
 - **源码位置**：`src/components/chat-message/reasoning-message/reasoning-message.vue`
 - **能力域**：消息系统
 - **能力说明**：渲染推理过程，覆盖加载、错误与 Markdown 内容展示。
 
-> **能力域**：消息系统
+> **导出说明**：`ReasoningMessage` **未**从包入口导出（入口同名是 TS interface）。消费方经 `MessageRender` / `MessageContainer` 使用。下文 `ReasoningMessageComp` 为文档站内部示例。
 
 AI 思维链（Chain-of-Thought）推理过程展示组件。由**可点击标题栏**和**内容区域**组成，内容区支持 Markdown 渲染。`duration` 传入后自动折叠一次，用户可随时点击标题展开/收起。
 
@@ -44,17 +45,19 @@ AI 思维链（Chain-of-Thought）推理过程展示组件。由**可点击标
 
 ```vue
 <template>
-  <ReasoningMessage
-    :content="content"
-    :status="status"
-  />
+  <MessageRender :message="message" />
 </template>
 
 <script setup lang="ts">
-  import { ReasoningMessage, MessageStatus } from '@blueking/chat-x';
-
-  const status = MessageStatus.Complete;
-  const content = ['让我分析一下这个问题...', '首先需要考虑以下几个方面...'];
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Reasoning,
+    status: MessageStatus.Complete,
+    content: ['让我分析一下这个问题...', '首先需要考虑以下几个方面...'],
+  };
 </script>
 ```
 
@@ -113,11 +116,12 @@ const { stop } = watch(
 通过 `v-model:collapsed` 从外部读取或设置折叠状态：
 
 ```vue
+<!-- 文档站内部示例：组件本体支持 v-model:collapsed；消费方一般经 MessageRender 渲染 -->
 <template>
   <button @click="collapsed = !collapsed">
     {{ collapsed ? '展开推理' : '收起推理' }}
   </button>
-  <ReasoningMessage
+  <ReasoningMessageComp
     v-model:collapsed="collapsed"
     :content="content"
     :status="status"
@@ -127,7 +131,7 @@ const { stop } = watch(
 
 <script setup lang="ts">
   import { ref } from 'vue';
-  import { ReasoningMessage, MessageStatus } from '@blueking/chat-x';
+  import { MessageStatus } from '@blueking/chat-x';
 
   const collapsed = ref(false);
   const status = MessageStatus.Complete;
@@ -220,17 +224,10 @@ interface ReasoningMessage {
   duration?: number; // 推理耗时（毫秒）
   name?: string;
 }
-
-enum MessageStatus {
-  Pending = 'pending',
-  Streaming = 'streaming',
-  Complete = 'complete',
-  Success = 'success',
-  Error = 'error',
-  Stop = 'stop',
-}
 ```
 
+> `MessageStatus` 完整取值见 [常量枚举](../../types/constants)。本组件完成态识别 `complete` / `success`（与标题文案表一致）。
+
 ## 关联组件
 
 - [MessageRender](/components/message/message-render) — reasoning 角色由其实例化

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-渲染工具返回内容，JSON 场景交给 DescPanel 展示。 源码位置：src/components/chat-message/tool-message/tool-message.vue。
+渲染工具返回内容；DescPanel 解析 JSON 为 key-value，嵌套值 JSON.stringify 后经 HighlightKeyword 展示。 源码位置：src/components/chat-message/tool-message/tool-message.vue。
 
 ### 关联组件
 - **assistant-message** — 结果常作为 assistant 消息中 toolCall.toolMessage 内联展示
@@ -12,51 +12,57 @@
 <!-- FULL DOC -->
 
 # ToolMessage 工具消息
+
 ## 源码事实
 
 - **源码位置**：`src/components/chat-message/tool-message/tool-message.vue`
 - **能力域**：消息系统
-- **能力说明**：渲染工具返回内容，JSON 场景交给 DescPanel 展示。
+- **能力说明**：渲染工具返回内容，JSON 场景交给 DescPanel + HighlightKeyword 展示。
 
-> **能力域**：消息系统
+> **导出说明**：`ToolMessage` **未**从包入口导出（入口同名是 TS interface）。消费方经 `MessageRender` / `ToolcallRender` 使用。下文 `ToolMessageComp` 为文档站内部示例。
 
-工具（Function Call）执行结果展示组件。内部通过 `DescPanel` 渲染，标题固定为"返回内容"，支持将 JSON 自动解析为 key-value 列表。
+工具执行结果展示组件。内部通过 `DescPanel` 渲染，标题固定为「返回内容」，可解析 JSON 为 key-value 列表。
 
-> **通常不需要直接使用此组件**。`ToolcallRender` 在 `toolCall.toolMessage` 有值时会自动内联渲染；`MessageContainer` 处理 `role: 'tool'` 消息时也会通过 `MessageRender` 自动渲染。
+> **通常不需要直接使用**。`ToolcallRender` 在 `toolCall.toolMessage` 有值时内联渲染；`role: 'tool'` 也可由 `MessageRender` 渲染。
 
 ## 渲染架构
 
 ```
 ToolMessage
-└── DescPanel（desc="content || (typeof error === 'string' ? error : undefined)"，title="返回内容"）
-      ├── JSON.parse(desc) 成功且结果为 object/array
-      │     └── key-value 列表（v-for 遍历）
-      │           值超长时截断 + overflow-tips tooltip
-      └── 其他（parse 失败 / 结果为基本类型）
-            └── 纯文本展示
+└── DescPanel（desc = content || (typeof error === 'string' ? error : undefined)，title="返回内容"）
+      ├── JSON.parse 成功且结果为 object/array（排除 null）
+      │     └── key-value 列表
+      │           · key / value 均经 HighlightKeyword 展示
+      │           · 嵌套 object/array：JSON.stringify 后展示（无 overflow-tips）
+      └── 其他（parse 失败 / 标量）
+            └── HighlightKeyword 纯文本
 ```
 
 ## 基础用法
 
 ```vue
 <template>
-  <ToolMessage
-    :content="content"
-    tool-call-id="call_1"
-    :duration="850"
-  />
+  <MessageRender :message="message" />
 </template>
 
 <script setup lang="ts">
-  import { ToolMessage } from '@blueking/chat-x';
-
-  const content = JSON.stringify({
-    city: '北京',
-    temperature: 22,
-    weather: '晴',
-    humidity: '45%',
-    wind: '东北风 3 级',
-  });
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: 't1',
+    messageId: 't1',
+    role: MessageRole.Tool,
+    status: MessageStatus.Complete,
+    toolCallId: 'call_1',
+    duration: 850,
+    content: JSON.stringify({
+      city: '北京',
+      temperature: 22,
+      weather: '晴',
+      humidity: '45%',
+      wind: '东北风 3 级',
+    }),
+  };
 </script>
 ```
 
@@ -70,18 +76,22 @@ ToolMessage
 
 ```vue
 <template>
-  <ToolMessage
-    content=""
-    :error="error"
-    tool-call-id="call_3"
-    :duration="5000"
-  />
+  <MessageRender :message="message" />
 </template>
 
 <script setup lang="ts">
-  import { ToolMessage } from '@blueking/chat-x';
-
-  const error = 'Connection timeout: database server is unreachable (timeout: 5000ms)';
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: 't3',
+    messageId: 't3',
+    role: MessageRole.Tool,
+    status: MessageStatus.Error,
+    toolCallId: 'call_3',
+    duration: 5000,
+    content: '',
+    error: 'Connection timeout: database server is unreachable (timeout: 5000ms)',
+  };
 </script>
 ```
 
@@ -98,25 +108,27 @@ ToolMessage
 | 解析失败（非法 JSON）       | 捕获异常，返回原字符串          | 纯文本                              |
 | `content` 和 `error` 均为空 | `''` → 解析失败                 | 空内容区                            |
 
-> **注意**：JSON 数组在 JavaScript 中 `typeof [] === 'object'` 为 `true`，因此数组会以 `0:`、`1:`、`2:` 为键渲染为 key-value 列表，而**非**纯文本。
+> **注意**：JSON 数组 `typeof [] === 'object'`，会以 `0:`、`1:`、`2:` 为键渲染为列表，而非整段纯文本。
 
-**嵌套对象值的处理**：当 value 本身是对象时，`{{ value }}` 会渲染为 `[object Object]`，但 hover 展示的 overflow-tips 会显示 `JSON.stringify(value)` 的完整字符串。
+**嵌套对象 / 数组值**：`DescPanel` 用 `JSON.stringify(value)` 转成字符串后交给 `HighlightKeyword`，**不再**使用 overflow-tips。
 
 ```typescript
-// ✅ 渲染为 key-value 列表
+// key-value 列表
 const jsonObject = '{"city":"北京","temperature":22}';
 
-// ✅ 渲染为 index-keyed 列表（0: item1, 1: item2）
+// index-keyed 列表（0: item1, 1: item2）
 const jsonArray = '["item1","item2","item3"]';
 
-// ✅ 渲染为纯文本（基本类型）
-const jsonNumber = '42';
-const jsonBool = 'true';
+// 嵌套值 stringify 展示
+const nested = '{"result":"success","data":{"city":"北京","meta":{"humidity":45}}}';
 
-// ✅ 渲染为纯文本（解析失败）
+// 标量 / 非法 JSON → 纯文本
+const jsonNumber = '42';
 const plainText = '查询成功，共返回 10 条记录。';
 ```
 
+**嵌套 JSON 渲染效果**
+
 ## 与 ToolcallRender 的关系
 
 `ToolcallRender` 在详情面板展开时，若 `toolCall.toolMessage` 有值，会在底部内联渲染 `ToolMessage`：
@@ -186,8 +198,8 @@ const messages = [
 
 | 属性名     | 类型               | 说明                                                                            |
 | ---------- | ------------------ | ------------------------------------------------------------------------------- |
-| content    | `string`           | 工具执行返回内容；与 `error` 通过 `\|\|` 决定优先级，**truthy 时 error 被忽略** |
-| error      | `string`           | 工具执行错误信息；仅当 `content` 为 falsy 且 `error` 为 `string` 类型时展示     |
+| content    | `string`                 | 工具执行返回内容；与 `error` 通过 `\|\|` 决定优先级，**truthy 时 error 被忽略** |
+| error      | `boolean \| string`      | 类型上可为 boolean；**仅当为 `string` 且 content 为 falsy 时**才会展示           |
 | toolCallId | `string`           | 关联的工具调用 ID（透传，组件内不使用）                                         |
 | duration   | `number`           | 工具执行耗时（毫秒，透传，组件内不使用）                                        |
 | status     | `MessageStatus`    | 消息状态（透传，组件内不使用）                                                  |
@@ -210,11 +222,15 @@ interface ToolMessage {
   content: string;
   toolCallId: string; // 关联的 ToolCall.id
   duration: number; // 工具执行耗时（毫秒）
-  error?: string; // 执行错误信息
+  error?: boolean | string; // 仅 string 会展示在 DescPanel
   name?: string;
 }
 ```
 
+### Events / Slots / Expose
+
+无。
+
 ## 关联组件
 
 - [AssistantMessage](/components/message/assistant-message) — toolCall.toolMessage 内联场景

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

@@ -31,7 +31,9 @@
 │   ├── "调用工具：" / "调用 MCP："（有 mcpName 时）
 │   ├── .toolcall-header-title（工具名，overflow-tips 溢出截断）
 │   └── .toolcall-status-title
-│         ├── Loading（仅 pending / streaming 时显示）
+│         ├── Loading（pending / streaming）
+│         ├── BkFlowSuccessIcon（success / complete / completed）
+│         ├── BkFlowFailedIcon（error）
 │         ├── 状态文案（调用中 / 调用成功 / 调用失败）
 │         └── .toolcall-duration（耗时，如 "(1.2s)"）
 │
@@ -76,16 +78,16 @@
 
 ## 调用状态
 
-`status` prop 同时控制头部的 CSS class（`toolcall-status-{status}`）、背景/边框颜色、状态文案和 Loading 动画：
+`status` prop 同时控制头部的 CSS class（`toolcall-status-{status}`）、背景/边框颜色、状态文案和状态图标：
 
-| `status`                | 状态文案 | 背景色            | 边框色    | Loading |
-| ----------------------- | -------- | ----------------- | --------- | ------- |
-| `pending` / `streaming` | 调用中   | `#fafbfd`         | `#dcdee5` | ✓       |
-| `complete` / `success`  | 调用成功 | `#ebfaf0`         | `#a1e3ba` | -       |
-| `error`                 | 调用失败 | `#fff0f0`         | `#f8b4b4` | -       |
-| 其他 / `undefined`      | 调用中   | —（无匹配 class） | —         | -       |
+| `status`                              | 状态文案 | 背景色            | 边框色    | 状态图标            |
+| ------------------------------------- | -------- | ----------------- | --------- | ------------------- |
+| `pending` / `streaming`               | 调用中   | `#fafbfd`         | `#dcdee5` | `Loading`           |
+| `complete` / `completed` / `success`  | 调用成功 | `#ebfaf0`         | `#a1e3ba` | `BkFlowSuccessIcon` |
+| `error`                               | 调用失败 | `#fff0f0`         | `#f8b4b4` | `BkFlowFailedIcon`  |
+| 其他 / `undefined`                    | 调用中   | —（无匹配 class） | —         | —                   |
 
-> **说明**：`statusTitle` 的 `switch` 语句中 `default` 与 `case Pending` 共享同一返回值，`streaming` 和未知 status 均命中 `default` 分支，显示"调用中"。Loading 动画由 `v-if="status === 'pending' || status === 'streaming'"` 单独控制。
+> **说明**：`statusTitle` 将 `Completed`（`completed`）与 `Complete` / `Success` 一并视为成功；主题 `$toolcallStatusMap` 同步提供 `completed` 色值。`default` 与 `case Pending` 共享「调用中」文案，`streaming` 与未知 status 命中 `default`。状态图标互斥：`pending` / `streaming` 显示 `Loading`；`success` / `complete` / `completed` 显示 `BkFlowSuccessIcon`；`error` 显示 `BkFlowFailedIcon`。
 
 **三种状态对比**
 
@@ -244,7 +246,13 @@ const assistantMessage = {
     v-for="toolCall in assistantMessage.toolCalls"
     :key="toolCall.id"
     :tool-call="toolCall"
-    :status="toolCall.toolMessage?.status ?? MessageStatus.Pending"
+    :status="
+      !toolCall.toolMessage
+        ? MessageStatus.Pending
+        : toolCall.toolMessage.error
+          ? MessageStatus.Error
+          : (toolCall.toolMessage.status ?? assistantMessage.status)
+    "
   />
 </template>
 ```