@blueking/chat-x 0.0.47-beta.4 → 0.0.49-beta.1

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

@@ -13,15 +13,16 @@
 <!-- FULL DOC -->
 
 # MessageRender 消息渲染器
+
 ## 源码事实
 
 - **源码位置**：`src/components/chat-message/message-render/message-render.vue`
 - **能力域**：消息系统
-- **能力说明**：按 message.role 分发到用户、助手、工具、推理、活动、中断等消息组件。
+- **能力说明**：按 `message.role` 分发到用户、助手、工具、推理、活动、中断等消息组件。
 
-> **能力域**：消息系统
+> **导出说明**：`MessageRender` **已**从 `@blueking/chat-x` 包入口导出，消费方可直接 import。下文 `MessageRenderComp` 为文档站相对路径 demo，与包入口行为一致。
 
-统一的消息渲染入口，通过 `message.role` 字段自动派发到对应的子组件。整个渲染过程由一个 `computed` 属性完成，无额外状态。
+统一的消息渲染入口，通过 `message.role` 派发到对应子组件；由单个 `computed` 完成，无额外状态。
 
 ## 渲染架构
 
@@ -151,7 +152,7 @@ MessageRender
 
 ### 流式输出（streaming）
 
-`status: 'streaming'` 时，`AssistantMessage` 内部展示打字光标，内容可实时追加：
+`status: 'streaming'` 时，默认回退的 `ContentRender` / `MarkdownContent` 会按流式规则补全未闭合语法；内容由外部逐步追加：
 
 ```vue
 <script setup lang="ts">
@@ -202,65 +203,74 @@ MessageRender
 
 ## 自定义内容渲染（default slot）
 
-`default` slot **仅对 `role: 'assistant'` 生效**，用于替换默认的 `ContentRender`。未提供 slot 时回退渲染 `<ContentRender :content="message.content" :status="message.status" />`。
+`default` slot **仅对 `role: 'assistant'` 生效**，用于替换默认的 `ContentRender`。
+
+未提供 slot 时，内部回退为：
+
+```ts
+h(ContentRender, { content: message.content || '', status: message.status }, /* codeHeader */)
+```
+
+自定义 slot 时，运行时参数来自 `AssistantMessage` 的 `v-bind`，**仅保证 `{ content }`**。需要 `status` 时请从外层 `message.status` 读取（不要依赖 slot 内的 `status`）。
 
 ```vue
 <template>
-  <MessageRender
-    :message="message"
-    :on-action="handleAction"
-  >
-    <template #default="{ content, status }">
-      <!-- 完全接管内容区域渲染 -->
+  <MessageRender :message="message">
+    <template #default="{ content }">
       <MyMarkdownRenderer
         :content="content"
-        :streaming="status === 'streaming'"
+        :streaming="message.status === 'streaming'"
       />
     </template>
   </MessageRender>
 </template>
 ```
 
-slot 参数类型与 `AssistantMessage` 的 slot 保持一致（`Partial<AssistantMessage>`），主要使用：
+| 参数      | 类型     | 说明                         |
+| --------- | -------- | ---------------------------- |
+| `content` | `string` | 消息内容（运行时保证）       |
 
-| 参数      | 类型            | 说明         |
-| --------- | --------------- | ------------ |
-| `content` | `string`        | 消息内容     |
-| `status`  | `MessageStatus` | 当前消息状态 |
+## 与 MessageContainer / ChatContainer 配合
 
-## 与 MessageContainer 配合
-
-在 `MessageContainer` 的 `default` slot 中使用，可替换默认的 `MessageRender` 渲染逻辑：
+自定义 `ChatContainer` 的 `#message` 时，插槽参数只有 `message` / `messageToolsStatus` / `onInterruptResume`。用户消息工具相关回调需由外层自行绑定透传，否则删除/编辑/复制/引用会失效（AI 消息工具栏在 `MessageContainer` 内渲染，不受 `#message` 影响）：
 
 ```vue
 <template>
-  <MessageContainer
+  <ChatContainer
     :messages="messages"
     :message-status="messageStatus"
     :on-agent-action="handleAgentAction"
     :on-user-action="handleUserAction"
-    @stop-streaming="handleStopStreaming"
+    :common-tippy-options="commonTippyOptions"
   >
-    <template #default="{ message, messageToolsStatus }">
-      <!-- 自定义 MessageRender 的行为 -->
+    <template #message="{ message, messageToolsStatus, onInterruptResume }">
       <MessageRender
         :message="message"
         :message-tools-status="messageToolsStatus"
         :on-action="handleUserAction"
-        :on-input-confirm="handleInputConfirm"
+        :on-input-confirm="(content, docSchema) => handleUserInputConfirm(message, content, docSchema)"
+        :on-shortcut-confirm="formModel => handleUserShortcutConfirm(message, formModel)"
+        :tippy-options="commonTippyOptions"
+        :on-interrupt-resume="onInterruptResume"
       >
         <template
           v-if="message.role === 'assistant'"
-          #default="{ content, status }"
+          #default="{ content }"
         >
           <MyCustomContent
             :content="content"
-            :status="status"
+            :status="message.status"
+          />
+        </template>
+        <template #codeHeader="{ language, token }">
+          <MyCodeActions
+            :language="language"
+            :token="token"
           />
         </template>
       </MessageRender>
     </template>
-  </MessageContainer>
+  </ChatContainer>
 </template>
 ```
 
@@ -280,11 +290,11 @@ slot 参数类型与 `AssistantMessage` 的 slot 保持一致（`Partial<Assista
 
 ### Slots
 
-| 插槽名           | 参数                                         | 说明                                                                                                    |
-| ---------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| answeredQuestion | `{ item, index, status }`                    | 自定义 UserQuestion 已回答回显，透传给 InterruptMessageRender → UserQuestionAnsweredCard 的 `#answer`   |
-| codeHeader       | `{ language: string; token: Token[] }`       | 代码块头部自定义操作区域，透传给 ContentRender → MarkdownContent → CodeContent；**仅对 assistant 生效** |
-| default          | `{ content: string, status: MessageStatus }` | 替换 AssistantMessage 的内容区域渲染；**仅对 `role: 'assistant'` 生效**                                 |
+| 插槽名           | 参数                                   | 说明                                                                                                    |
+| ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| answeredQuestion | `{ item, index, status }`              | 自定义 UserQuestion 已回答回显，透传给 InterruptMessageRender → UserQuestionAnsweredCard 的 `#answer`   |
+| codeHeader       | `{ language: string; token: Token[] }` | 代码块头部自定义操作区域，透传给 ContentRender → MarkdownContent → CodeContent；**仅对 assistant 生效** |
+| default          | `{ content: string }`                  | 替换 AssistantMessage 内容区；**仅对 assistant 生效**；运行时仅保证 `content`（`status` 请读外层 message） |
 
 ## 消息类型映射
 
@@ -314,6 +324,7 @@ enum MessageRole {
   Tool = 'tool',
   Activity = 'activity',
   Loading = 'loading',
+  Interrupt = 'interrupt',
 }
 
 // 消息状态

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

@@ -361,11 +361,15 @@ const CONST_UPDATE_TOOLS = [
 
 ```typescript
 import { MessageToolsStatus, type IToolBtn } from '@blueking/chat-x';
+import type { Component, VNode } from 'vue';
 
 interface IToolBtn {
-  id?: keyof typeof ToolIconsMap; // 工具唯一标识；与 ToolIconsMap 匹配时显示内置图标，否则显示 name 文本
+  id?: (string & {}) | ToolIcons; // 工具唯一标识；命中 ToolIconsMap 显示内置图标，否则显示 name 文本；支持业务自定义字符串
   name?: string; // 工具名称，无对应图标时显示；也用作 tooltip fallback
   description?: string; // tooltip 文本
+  icon?: Component | VNode; // 自定义图标（组件/VNode），优先级高于内置 ToolIconsMap[id]
+  hidden?: boolean; // 按 id 合并时隐藏该按钮（仅在 MessageContainer/ChatContainer 合并语义下生效）
+  triggerSelection?: boolean; // 标记点击后进入多选态（复用 share 选择流程），确认走 confirmShare
 }
 
 enum MessageToolsStatus {

package/dist/mcp/generated/docs/model-selector.md

@@ -0,0 +1,157 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+聊天输入区的模型下拉选择器，支持搜索过滤、能力标签与键盘导航。 源码位置：src/components/chat-input/model-selector/model-selector.vue。
+
+### 关联组件
+- **chat-input** — 传入 models 后在发送按钮左侧默认渲染
+- **input-attachment** — 通过 before-send 插槽与发送按钮成组布局
+
+---
+<!-- FULL DOC -->
+
+# ModelSelector 模型选择器
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-input/model-selector/model-selector.vue`
+- **能力域**：输入交互
+- **能力说明**：基于 Tippy 下拉的模型选择器，包含触发器、搜索面板与能力标签展示；数据过滤逻辑由 `useModelSelector` composable 承担。
+
+> **能力域**：输入交互
+
+可在 [ChatInput](/components/input/chat-input) 传入 `models` 后自动出现在发送按钮左侧，也可单独使用。
+
+## 组件结构
+
+```
+ModelSelector（Tippy 容器，theme: ai-model-selector）
+├── ModelSelectorTrigger（触发器：图标 + 名称 + 箭头）
+└── ModelSelectorPanel（下拉面板）
+    ├── 搜索框（展开后自动聚焦）
+    └── 模型列表（支持键盘导航、选中态、禁用态、能力标签）
+```
+
+## 基础用法
+
+选中值为模型的 `llm_name`；能力标签由组件依据 `property`（`support_thinking` / `support_thinking_quick` / `support_vision`）自动派生，无需调用方传入。
+
+```vue
+<template>
+  <ModelSelector
+    v-model="selectedModel"
+    :models="models"
+    @change="handleModelChange"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ModelSelector, type IModelOption } from '@blueking/chat-x';
+
+  // 选中值为 llm_name
+  const selectedModel = ref('DeepSeek-V4-Pro-Online-32k');
+  const models: IModelOption[] = [
+    {
+      id: 119,
+      llm_code: 'DeepSeek-V4-Pro-Online-32k',
+      llm_name: 'DeepSeek-V4-Pro-Online-32k',
+      llm_type: 'chat.completion',
+      space_auth_mode: 'APPLY',
+      user_auth_mode: 'PUBLIC',
+      max_token_size: 4096,
+      icon: 'https://example.com/deepseek.png',
+      description: 'DeepSeek-V4-Pro 旗舰版本，支持超长上下文与复杂任务处理',
+      base_model: 'deepseek',
+      tag_names: [],
+      // support_thinking → 深度思考、support_vision → 图生文
+      property: { support_thinking: true, support_vision: true, max_model_len: 32000 },
+    },
+  ];
+
+  const handleModelChange = (model: IModelOption) => {
+    console.log('选中模型:', model);
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名            | 类型                                                                       | 默认值           | 说明                                   |
+| ----------------- | -------------------------------------------------------------------------- | ---------------- | -------------------------------------- |
+| disabled          | `boolean`                                                                  | `false`          | 是否禁用整个选择器                     |
+| models            | `IModelOption[]`                                                           | `[]`             | 可选模型列表                           |
+| placeholder       | `string`                                                                   | `选择模型`       | trigger 无选中时的占位文案             |
+| searchPlaceholder | `string`                                                                   | `搜索模型关键字` | 搜索框占位文案                         |
+| tippyOptions      | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | —                | 透传给 Tippy 的额外配置                |
+
+### v-model
+
+| 属性名 | 类型     | 说明                          |
+| ------ | -------- | ----------------------------- |
+| —      | `string` | 当前选中模型的 `llm_name` 值 |
+
+### Events
+
+| 事件名 | 参数                    | 说明                 |
+| ------ | ----------------------- | -------------------- |
+| change | `(model: IModelOption)` | 用户选中模型时触发   |
+
+## 类型定义
+
+```typescript
+import type { IModelCapability, IModelOption, IModelProperty, ModelCapabilityTheme } from '@blueking/chat-x';
+
+type ModelCapabilityTheme = 'default' | 'primary' | 'success' | 'warning';
+
+// 能力标签由组件依据 property 派生（文案走内置 i18n）
+interface IModelCapability {
+  theme?: ModelCapabilityTheme;
+  text: string;
+}
+
+// 模型能力属性，决定派生出的能力标签
+interface IModelProperty {
+  agent_type?: string;
+  default?: boolean;
+  is_self_host?: boolean;
+  max_model_len?: number;
+  support_summary?: boolean;
+  support_thinking?: boolean; // → 深度思考
+  support_thinking_quick?: boolean; // → 快速思考
+  support_tools?: boolean;
+  support_vision?: boolean; // → 图生文
+  support_window?: boolean;
+}
+
+// 模型选项，贴合后端模型接口结构
+interface IModelOption {
+  base_model?: string;
+  description?: string; // 选项 hover 的 title 提示
+  disabled?: boolean; // 前端扩展字段，禁用项不可选中
+  icon?: string;
+  id: number;
+  llm_code: string;
+  llm_name: string; // 展示名，同时作为选中值
+  llm_type: string;
+  max_token_size: number;
+  property: IModelProperty;
+  space_auth_mode: string;
+  tag_names?: string[];
+  user_auth_mode: string;
+}
+```
+
+## 注意事项
+
+1. `models` 为空或 `disabled` 为 `true` 时，下拉不会展开。
+2. 选中值为模型的 `llm_name`；能力标签由组件依据 `property` 的 `support_thinking` / `support_thinking_quick` / `support_vision` 派生，文案走内置 i18n。
+3. `description` 会作为选项 hover 的 `title` 提示展示。
+4. 展开面板后会自动聚焦搜索框；列表支持键盘上下选择与 Enter 确认（复用 `useMenuKeydown`）。
+
+## 关联组件
+
+- [ChatInput](/components/input/chat-input)：传入 `models` 后默认在发送按钮左侧渲染本组件，也可通过 `#model-selector` 插槽完全自定义。
+- [ChatContainer](/components/setup/chat-container)：透传 `models` 与 `v-model:selected-model`，并向上 emit `modelChange`。

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;

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

@@ -30,8 +30,9 @@ div.ai-tool-btn（v-tippy，flex，min-width: 20px，height: 20px，border-radiu
   disabled=true → .is-disabled（color: #979ba5; cursor: not-allowed）
   :not(.is-disabled):hover → color: #4d4f56; background: #eaebf0
   │
-  └── <slot>（默认内容，可完全自定义）
-        ├── [id && id in ToolIconsMap] → <component :is="ToolIconsMap[id]" />（SVG 图标）
+  └── <slot>（默认内容，可完全自定义；优先级最高）
+        ├── [icon] → <component :is="icon" />（自定义图标组件/VNode，优先级高于内置图标）
+        ├── [id && id in ToolIconsMap] → <component :is="ToolIconsMap[id]" />（内置 SVG 图标）
         └── [其他] → <div>{{ name }}</div>（文本回退，XSS 安全）
 
 Tippy：content=description, theme='ai-chat-box', disabled=true 时 onShow 返回 false 不显示
@@ -195,6 +196,28 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 
 `id` 不在 `ToolIconsMap` 时渲染 `name` 文本，适用于自定义扩展场景：
 
+## 自定义图标（icon 属性）
+
+当内置 `ToolIconsMap` 未覆盖所需图标时，可通过 `icon` 传入自定义图标组件或 VNode（如业务新增的「保存」按钮）。`icon` 的渲染优先级高于内置图标，因此即便 `id` 命中内置图标，也会以 `icon` 为准。
+
+```vue
+<template>
+  <ToolBtn
+    id="save"
+    name="保存"
+    description="保存该回答"
+    :icon="DownloadIcon"
+    @click="handleClick"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ToolBtn, DownloadIcon } from '@blueking/chat-x';
+</script>
+```
+
+> 优先级从高到低：默认插槽 `>` `icon` 属性 `>` 内置 `ToolIconsMap[id]` `>` `name` 文本回退。
+
 ## 自定义插槽内容
 
 通过默认插槽可完全替换内置图标/文本，适用于预置 `ToolIconsMap` 未覆盖的图标场景（如侧栏全屏按钮）：
@@ -225,9 +248,10 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 
 | 属性名       | 类型                                                                       | 必填 | 默认值 | 说明                                                                                                               |
 | ------------ | -------------------------------------------------------------------------- | ---- | ------ | ------------------------------------------------------------------------------------------------------------------ |
-| id           | `keyof typeof ToolIconsMap`                                                | 否   | —      | 按钮标识；在 `ToolIconsMap` 中时渲染对应 SVG 图标，否则渲染 `name` 文本；使用插槽自定义内容时可省略                  |
+| id           | `(string & {}) \| ToolIcons`                                               | 否   | —      | 按钮标识；命中 `ToolIconsMap` 时渲染对应 SVG 图标，否则渲染 `name` 文本；支持业务自定义任意字符串（如 `save`）      |
 | name         | `string`                                                                   | 否   | —      | 按钮名称；`id` 无对应图标时作为文本内容渲染                                                                        |
 | description  | `string`                                                                   | 否   | —      | Tippy tooltip 内容；`disabled=true` 时不显示 tooltip                                                               |
+| icon         | `Component \| VNode`                                                        | 否   | —      | 自定义图标组件或 VNode；优先级高于内置 `ToolIconsMap[id]`，低于默认插槽                                             |
 | active       | `boolean`                                                                  | 否   | —      | 激活态；`true` 时追加 `.is-active`（字色由 `id` 决定：`like`/`activeLike` 为蓝色 `#3a84ff`，其他为红色 `#E71818`） |
 | disabled     | `boolean`                                                                  | 否   | —      | 禁用态；`true` 时追加 `.is-disabled`，阻止 click 事件，隐藏 tooltip                                                |
 | tippyOptions | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | 否   | —      | 自定义 Tippy 配置，与内部默认配置合并；可用于控制 `content`、`appendTo`、`placement` 等                            |
@@ -247,11 +271,16 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 ## 类型定义
 
 ```typescript
+import type { Component, VNode } from 'vue';
+
 // 来自 @blueking/chat-x 导出
 interface IToolBtn {
-  id?: keyof typeof ToolIconsMap; // 预置 ID；省略时走 name 文本或插槽
+  id?: (string & {}) | ToolIcons; // 内置 ID 保留自动补全，同时允许业务自定义任意字符串（如 'save'）
   name?: string;
   description?: string;
+  icon?: Component | VNode; // 自定义图标，优先级高于内置 ToolIconsMap
+  hidden?: boolean; // 按 id 合并时隐藏该按钮（如 { id: 'share', hidden: true } 移除内置项）
+  triggerSelection?: boolean; // 标记点击后进入多选态（复用 share 选择流程），确认走 confirmShare
 }
 
 // ToolBtn 完整 Props

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 内联场景