@blueking/chat-x 0.0.49-beta.9 → 0.0.51-beta.1

package/dist/mcp/generated/docs/file-content.md

@@ -19,26 +19,34 @@
 
 > **能力域**：媒体文件
 
-文件列表展示组件，支持图片缩略图预览、点击图片全屏预览（`ImagePreview`）、文档卡片展示（文件名/扩展名/文件大小）、图片加载失败占位和删除操作。
+文件列表展示组件，支持图片缩略图预览、点击图片全屏预览（`ImagePreview`）、文件卡片展示（类型图标 / 文件名 / 文件大小）、图片加载失败占位和删除操作。
+
+内部由两个子组件承载单项渲染：
+
+| 子组件             | 源码位置                                                            | 职责                                          |
+| ------------------ | ------------------------------------------------------------------- | --------------------------------------------- |
+| `UploadImageItem`  | `src/components/chat-content/file-content/upload-image-item.vue`  | 图片缩略图、加载失败占位、hover 删除徽标      |
+| `UploadFileItem`   | `src/components/chat-content/file-content/upload-file-item.vue`   | 180px 文件卡片（`FileIcon` + 文件名 + 大小） |
 
 ## 渲染决策逻辑
 
-每个文件按以下优先级决定渲染方式：
+先分组、再渲染。设计稿要求**图片始终排在文件前方**，两类各自成行：
 
 ```
-file.url 存在？
-├── 是 → 图片模式（用 file.url 作为 <img src>，点击可全屏预览）
-│        图片加载失败 → 错误占位（粉色背景 + 红色边框 + 灰色图标）
-└── 否 → 检查 mimeType 或 file.file?.type
-         ├── 以 'image/' 开头 → 图片模式（用 getFilePreviewUrl(file.file) 作为 src，点击可全屏预览）
-         └── 其他            → 文档卡片模式（图标 + 文件名 + 扩展名 + 大小）
+splitUploadFiles(files)  // 单次遍历
+├── 图片组（.ai-files-content-row.is-images）
+│     判定依据：mimeType 或 file.file?.type 以 'image/' 开头
+│     src：file.url 优先，否则用本地 File 的 blob URL（按 key 缓存，移除 / 卸载时 revoke）
+│     加载失败 → 错误占位（粉色背景 + 红色边框 + 灰色图标），且不进入预览列表
+└── 文件组（.ai-files-content-row.is-files）
+      文件卡片：类型图标（FileIcon，按文件名解析扩展名）+ 文件名 + 文件大小
 ```
 
-> **注意**：`file.url` 存在时**无论文件 MIME 类型是什么**都会走图片模式。若要将 PDF 等非图片文件显示为文档卡片，确保不设置 `url` 字段（或设为 `undefined`）。
+> **是否为图片只看 MIME，不看 `url`。** 解除上传类型限制后，任意文件上传成功都会拿到 `url`，若按 `url` 判断会把 PDF / DOC 渲染成破图。因此 `url` 只决定 `<img src>` 从哪里来，不参与图片判定。
 
-## 基础用法（文档文件）
+## 基础用法（文件卡片）
 
-无 `url` 字段、MIME 类型非 `image/*` 的文件，渲染为文档卡片（文档图标 + 文件名 + 扩展名 + 大小）：
+MIME 类型非 `image/*` 的文件，渲染为固定宽 180px 的文件卡片（类型图标 + 文件名 + 大小）。类型图标与文件产物侧栏共用 `FileIcon` 的扩展名映射，`pdf` / `py` / `docx` 等各有专属图标，未登记的扩展名回退兜底图标：
 
 ```vue
 <template>
@@ -64,11 +72,11 @@ file.url 存在？
 </script>
 ```
 
-**渲染效果**（悬停文件卡片，右上角出现删除按钮）
+**渲染效果**（悬停文件卡片，底色加深并在右上角出现删除徽标）
 
 ## 图片文件预览
 
-设置了 `url` 字段时，渲染为 48×48 的图片缩略图（`cursor: zoom-in`）。点击图片可打开全屏预览（内部集成 `ImagePreview` 组件），支持缩放、旋转、下载等操作：
+MIME 为 `image/*` 时渲染为图片缩略图（`cursor: zoom-in`）。点击图片可打开全屏预览（内部集成 `ImagePreview` 组件），支持缩放、旋转、下载等操作：
 
 ```vue
 <script setup lang="ts">
@@ -77,9 +85,9 @@ file.url 存在？
 
   const imageFiles = ref<Partial<UploadFile>[]>([
     {
-      url: 'https://example.com/cat.jpg', // 有 url → 图片模式
+      url: 'https://example.com/cat.jpg',
       filename: 'cat.jpg',
-      mimeType: 'image/jpeg',
+      mimeType: 'image/jpeg', // 图片判定依据
       file: new File([''], 'cat.jpg', { type: 'image/jpeg' }),
     },
     {
@@ -120,9 +128,9 @@ file.url 存在？
 
 `<img>` 触发 `onerror` 时，切换为粉色背景 + 红色边框的错误占位：
 
-## 混合文件（图片 + 文档）
+## 混合文件（图片 + 文件）
 
-同一列表中可同时包含图片和文档文件，横向 flex 布局、换行排列：
+同一列表可同时包含图片和其他文件，组件内部自动把图片排在前一行、文件排在后一行，各行内部横向排列并按需换行：
 
 ```vue
 <script setup lang="ts">
@@ -148,19 +156,20 @@ file.url 存在？
 
 ## 仅有 filename（无 File 对象）
 
-从服务端恢复的历史文件没有 `File` 对象时，仍可渲染文档卡片，但**文件大小不显示**，扩展名从 `filename` 或 `mimeType` 推断：
+从服务端恢复的历史文件没有 `File` 对象时仍可渲染文件卡片，类型图标从 `filename` 推断。文件大小取 `size` 字段；未下发 `size` 时大小节点不渲染：
 
 ```vue
 <script setup lang="ts">
   const remoteFiles = [
-    // 无 file 对象，文件大小显示为空
+    // 无 file 对象，未带 size，文件大小不渲染
     { filename: 'server-report.pdf', mimeType: 'application/pdf' },
-    { filename: 'config.json', mimeType: 'application/json' },
+    // 带 size 时正常显示「1.00M」
+    { filename: 'config.json', mimeType: 'application/json', size: 1024 * 1024 },
   ];
 </script>
 ```
 
-**渲染效果**（大小区域为空）
+**渲染效果**（未带 `size` 的项无大小行）
 
 ## 在 ChatInput 中使用
 
@@ -199,10 +208,20 @@ file.url 存在？
 
 ### Props
 
-| 属性名   | 类型                    | 默认值  | 必填 | 说明                            |
-| -------- | ----------------------- | ------- | ---- | ------------------------------- |
-| files    | `Partial<UploadFile>[]` | -       | ✅   | 文件列表                        |
-| readonly | `boolean`               | `false` | -    | 只读模式，`true` 时隐藏删除按钮 |
+| 属性名   | 类型                    | 默认值    | 必填 | 说明                                        |
+| -------- | ----------------------- | --------- | ---- | ------------------------------------------- |
+| files    | `Partial<UploadFile>[]` | -         | ✅   | 文件列表                                    |
+| readonly | `boolean`               | `false`   | -    | 只读模式，`true` 时隐藏删除徽标与 hover 态 |
+| variant  | `'input' \| 'message'`  | `'input'` | -    | 展示形态，见下方「展示形态」                |
+
+### 展示形态（variant）
+
+只影响图片缩略图的圆角描边与整体对齐，文件卡片两种形态一致。图片尺寸规则两种形态相同：**定高 48px，宽度按原图比例，并在 48~120px 之间夹取**（竖图不至于过窄，长图不会撑破容器），超出部分由 `object-fit: cover` 裁切。
+
+| variant     | 使用场景           | 图片圆角 / 描边 | 对齐   |
+| ----------- | ------------------ | --------------- | ------ |
+| `'input'`   | 输入框内待发送态   | 8px / `#f0f1f5` | 左对齐 |
+| `'message'` | 用户消息内已发送态 | 4px / `#eaebf0` | 右对齐 |
 
 ### Events
 
@@ -214,19 +233,21 @@ file.url 存在？
 
 ### 图片模式
 
-| 条件                               | 图片 src                         | 点击行为       |
-| ---------------------------------- | -------------------------------- | -------------- |
-| `file.url` 有值（优先）            | `file.url`                       | 打开全屏预览   |
-| MIME 以 `image/` 开头（无 url 时） | `URL.createObjectURL(file.file)` | 打开全屏预览   |
-| 图片加载失败                       | 错误占位                         | 不进入预览列表 |
+| 条件                | 图片 src                                          | 点击行为       |
+| ------------------- | ------------------------------------------------- | -------------- |
+| `file.url` 有值     | `file.url`                                        | 打开全屏预览   |
+| 无 url、有 `File`   | `URL.createObjectURL(file.file)`（按 key 缓存）  | 打开全屏预览   |
+| 图片加载失败        | 错误占位                                          | 不进入预览列表 |
+
+blob URL 按附件 key 缓存，同一文件重复渲染不会重复创建；文件被移除或组件卸载时统一 `revokeObjectURL`。
 
-### 文档卡片模式
+### 文件卡片模式
 
-| 字段     | 取值优先级                                                                                                   |
-| -------- | ------------------------------------------------------------------------------------------------------------ |
-| 文件名   | `file.filename` → `file.file?.name`                                                                          |
-| 扩展名   | 有 `file.file`：取文件名最后一段 `.xxx` 或 MIME 后缀<br>无 `file.file`：取 `filename` 后缀 → `mimeType` 后缀 |
-| 文件大小 | 仅当有 `file.file`（`File` 对象）时显示，否则为空                                                            |
+| 字段     | 取值优先级                                    |
+| -------- | --------------------------------------------- |
+| 文件名   | `file.filename` → `file.file?.name`           |
+| 类型图标 | 由文件名解析扩展名，交给 `FileIcon` 映射      |
+| 文件大小 | `file.file?.size` → `file.size`；都没有则不渲染 |
 
 ## 类型定义
 
@@ -249,48 +270,43 @@ type UploadFile = BinaryInputContent & {
 // 二进制内容基础类型
 interface BinaryInputContent {
   type: 'binary';
-  url?: string; // 文件访问地址，存在时强制走图片模式
-  filename?: string; // 文件名（用于文档卡片）
-  mimeType?: string; // MIME 类型（用于图片判断和扩展名推断）
+  url?: string; // 文件访问地址，只决定 <img src> 来源，不参与图片判定
+  filename?: string; // 文件名（文件卡片展示 + 类型图标解析）
+  mimeType?: string; // MIME 类型（图片判定依据）
+  size?: number; // 文件字节数，发送时由原始 File 写入
 }
 ```
 
-## 工具函数（内部使用）
-
-```typescript
-// 判断是否走图片模式
-// ⚠️ file.url 存在时直接返回 true，不判断 MIME 类型
-const isImage = (file: Partial<UploadFile>): boolean => {
-  if (file.url) return true;
-  return isImageFile(file.mimeType || file.file?.type);
-};
-
-// 判断 MIME 类型是否为图片
-const isImageFile = (mimeType?: string): boolean => {
-  if (!mimeType) return false;
-  return mimeType.startsWith('image/');
-};
-
-// 获取 File 对象的临时预览 URL（无 url 时的图片模式备选）
-const getFilePreviewUrl = (file?: File): string => {
-  if (!file) return '';
-  return URL.createObjectURL(file);
-};
+## 工具函数（`src/utils/upload-file.ts`）
 
-// 获取文件扩展名
-const getFileExtension = (file?: File): string => {
-  if (!file) return '';
-  return file.name.split('.').pop() || file.type?.split('/').pop() || '';
-};
+组件内的取值与分组逻辑都收敛在这里，`ChatInput`、`UserMessage` 共用同一套判定：
 
-// 格式化文件大小（需要 File 对象）
-const formatFileSize = (file?: File): string => {
-  if (!file) return '';
-  const size = file.size;
-  const units = ['B', 'KB', 'M', 'GB'];
-  const index = Math.floor(Math.log2(size || 1) / 10);
-  return `${(size / Math.pow(1024, index)).toFixed(2)} ${units[index]}`;
-};
+```typescript
+import {
+  getFileIdentity,
+  getUploadFileKey,
+  getUploadFileName,
+  getUploadFileSize,
+  isUploadImageFile,
+  splitUploadFiles,
+} from '@blueking/chat-x';
+
+// File 身份：文件名 + 大小 + 修改时间，用于去重与列表 key
+getFileIdentity(file); // 'report.pdf_2048_1700000000000'
+
+// 附件稳定 key：待发送态用 File 身份（上传成功回填 url 后不变），已发送态退回 url / 文件名
+getUploadFileKey({ file }); // 'report.pdf_2048_1700000000000'
+getUploadFileKey({ url: 'https://x/a.pdf' }); // 'https://x/a.pdf'
+
+// 是否按图片渲染：只看 MIME，有 url 也不例外
+isUploadImageFile({ mimeType: 'application/pdf', url: 'https://x/a.pdf' }); // false
+
+// 文件名 / 字节数取值优先级
+getUploadFileName({ filename: 'remote.pdf', file }); // 'remote.pdf'
+getUploadFileSize({ size: 2048 }); // 2048
+
+// 单次遍历分出图片组与其他文件组（图片在前）
+splitUploadFiles(files); // { imageFiles, otherFiles }
 ```
 
 ## 使用场景

package/dist/mcp/generated/docs/file-upload-btn.md

@@ -19,16 +19,18 @@
 
 > **能力域**：输入交互
 
-聊天输入框内置的文件上传触发按钮，点击后弹出系统文件选择框。内部包含隐藏的 `<input type="file">` 与可见的图标按钮；在按钮层对**单文件**做大小与空文件过滤，**已选文件个数上限**由上层（如 `ChatInput`）统一校验并提示，避免按钮与输入区各弹一条错误提示。
+聊天输入框内置的文件上传触发按钮，点击后弹出系统文件选择框。内部包含隐藏的 `<input type="file">` 与可见的图标按钮；**不限制文件类型**，在按钮层只对**单文件**做大小与空文件过滤，**已选文件个数上限**由上层（如 `ChatInput`）统一校验并提示，避免按钮与输入区各弹一条错误提示。
 
 ## 组件结构
 
 ```
 .ai-file-upload-btn（display: flex，align-items: center）
 ├── input[type="file"]（.file-upload-btn-input，display: none，multiple，:accept）
+│     accept 缺省时不下发该属性，系统选择框不过滤任何类型
 │     触发后走 handleFileInputChange → 校验 → emit upload → target.value = ''
-└── span.ai-shortcut-btn.file-upload-btn-icon（24×24px，color: #979ba5，hover: cursor: pointer）
-      v-tippy: "上传图片, 最多支持上传 3 个, 最大支持 2.4MB"（theme: ai-chat-box，offset: [0, 16]，可通过 tippyOptions 扩展）
+└── span.ai-shortcut-btn.file-upload-btn-icon（热区 32×32px / 圆角 8px；图标字号跟随 --ai-icon-size-sm：small=16px、normal=18px；color: #979ba5；hover: #f0f1f5）
+      v-tippy: "上传文件，最多支持 {count} 个，单个最大 {size}MB"
+        （{count} / {size} 由 MAX_UPLOAD_FILES 与 MAX_UPLOAD_FILE_SIZE 运行时填充，theme: ai-chat-box，offset: [0, 16]，可通过 tippyOptions 扩展）
       @click → fileInputRef.click()
       └── <slot> 默认：FileUploadIcon
 ```
@@ -61,7 +63,7 @@
 
 > `multiple` prop 声明存在但当前模板中 `input` 的 `multiple` 属性为**硬编码**（非 `:multiple="multiple"` 绑定），始终允许多选，该 prop 暂时无实际效果。
 
-> **`maxFiles` prop**：当前版本在按钮内**不参与截断或计数校验**，仅作类型与文档预留；列表最多几个文件由上层（如 `ChatInput` 的 `MAX_UPLOAD_FILES`）控制。详见 [ChatInput 文件上传](/components/input/chat-input#file-upload)。
+> **文件类型不做限制**：组件不再默认 `accept="image/*"`，任意类型文件都可选择。若业务需要收窄，显式传入 `accept`。个数上限由上层（如 `ChatInput` 的 `MAX_UPLOAD_FILES`）控制，详见 [ChatInput 文件上传](/components/input/chat-input#file-upload)。
 
 ## 基础用法
 
@@ -84,11 +86,14 @@
 
 ## 限制文件类型
 
-通过 `accept` 属性控制系统文件选择框的过滤条件，遵循 `<input type="file">` 的 `accept` 规范：
+默认**不限制**文件类型。需要收窄时通过 `accept` 属性控制系统文件选择框的过滤条件，遵循 `<input type="file">` 的 `accept` 规范：
 
 ```vue
 <template>
-  <!-- 仅图片（默认） -->
+  <!-- 不限制类型（默认，不下发 accept） -->
+  <FileUploadBtn @upload="handleUpload" />
+
+  <!-- 仅图片 -->
   <FileUploadBtn
     accept="image/*"
     @upload="handleUpload"
@@ -99,12 +104,6 @@
     accept=".pdf,.doc,.docx,.xlsx,.pptx"
     @upload="handleUpload"
   />
-
-  <!-- 不限制类型 -->
-  <FileUploadBtn
-    accept="*/*"
-    @upload="handleUpload"
-  />
 </template>
 ```
 
@@ -126,12 +125,11 @@
 
 ### Props
 
-| 属性名       | 类型           | 默认值      | 说明                                                                 |
-| ------------ | -------------- | ----------- | -------------------------------------------------------------------- |
-| accept       | `string`       | `'image/*'` | 文件选择框过滤类型，遵循 `<input accept>` 规范                       |
-| maxFiles     | `number`       | `3`         | 预留字段，**当前不在按钮内生效**；个数上限见 `ChatInput` 与全局常量 |
-| multiple     | `boolean`      | `true`      | 声明属性（当前版本未实际绑定到 input，始终多选）                     |
-| tippyOptions | `AITippyProps` | —           | 扩展 tooltip 配置，会与内置配置合并                                |
+| 属性名       | 类型           | 默认值 | 说明                                                                       |
+| ------------ | -------------- | ------ | -------------------------------------------------------------------------- |
+| accept       | `string`       | —      | 文件选择框过滤类型，遵循 `<input accept>` 规范；缺省时不下发，不限制类型 |
+| multiple     | `boolean`      | `true` | 声明属性（当前版本未实际绑定到 input，始终多选）                           |
+| tippyOptions | `AITippyProps` | —      | 扩展 tooltip 配置，会与内置配置合并                                        |
 
 ### Events
 

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

@@ -568,6 +568,7 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 | messageStatus            | `MessageStatus`                                                                              | —       | 当前整体消息状态，控制底部「停止生成」按钮显示；`ChatContainer` 会结合末尾 Loading 占位推导 `fetching` 等再传入                                                                                                   |
 | messageTools             | `IToolBtn[]`                                                                                 | —       | AI 消息左侧工具（复制/引用等）的自定义配置；按 `id` 与内置 `CONST_MESSAGE_TOOLS` 合并（覆盖同 id、追加新 id、`hidden` 过滤），详见「自定义消息工具栏」 |
 | updateTools              | `IToolBtn[]`                                                                                 | —       | AI 消息右侧反馈工具（点赞/踩/删除等）的自定义配置；按 `id` 与内置 `CONST_UPDATE_TOOLS` 合并，规则同上                                     |
+| userMessageTools         | `IToolBtn[]`                                                                                 | —       | 自定义用户消息工具组，透传给 `MessageRender` → `UserMessage`；按 id 与 `CONST_USER_MESSAGE_TOOLS` 合并，`{ id, hidden: true }` 可隐藏     |
 | messageToolsStatus       | `MessageToolsStatus`                                                                         | —       | 工具栏状态，透传给 `MessageTools` 和 `MessageRender`                                                                                     |
 | messageToolsTippyOptions | `AITippyProps`                                                                               | —       | 透传给 `MessageTools` 和 `MessageRender`（进而透传给 `UserMessage` 的工具栏）的 Tippy 配置，用于自定义 tooltip 挂载点、位置等（如 `appendTo`、`placement`、`zIndex`） |
 | enableSelection          | `boolean`                                                                                    | `false` | 是否启用多选模式                                                                                                                         |

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

@@ -281,6 +281,7 @@ h(ContentRender, { content: message.content || '', status: message.status }, /*
 | 属性名             | 类型                                                                       | 默认值 | 说明                                              |
 | ------------------ | -------------------------------------------------------------------------- | ------ | ------------------------------------------------- |
 | message            | `Partial<Message>`                                                         | —      | **必填**，消息对象，`role` 字段决定渲染哪个子组件 |
+| messageTools       | `IToolBtn[]`                                                               | —      | 自定义用户消息工具组；**仅转发给 `UserMessage`**  |
 | messageToolsStatus | `MessageToolsStatus`                                                       | —      | 工具按钮状态；**仅转发给 `UserMessage`**          |
 | onAction           | `(tool: IToolBtn) => Promise<string[] \| void>`                            | —      | 工具操作回调；**仅转发给 `UserMessage`**          |
 | onInputConfirm     | `(content: UserMessage['content'], docSchema: TagSchema) => Promise<void>` | —      | 用户编辑确认回调；**仅转发给 `UserMessage`**      |
@@ -300,7 +301,7 @@ h(ContentRender, { content: message.content || '', status: message.status }, /*
 
 | `MessageRole` | 渲染组件           | prop 路由                                                                                               | 说明                  |
 | ------------- | ------------------ | ------------------------------------------------------------------------------------------------------- | --------------------- |
-| `user`        | `UserMessage`      | `message` + `onAction` + `onInputConfirm` + `onShortcutConfirm` + `messageToolsStatus` + `tippyOptions` | 用户发送的消息        |
+| `user`        | `UserMessage`      | `message` + `onAction` + `onInputConfirm` + `onShortcutConfirm` + `messageTools` + `messageToolsStatus` + `tippyOptions` | 用户发送的消息        |
 | `assistant`   | `AssistantMessage` | `message` + `default slot`                                                                              | AI 助手回复消息       |
 | `info`        | `InfoMessage`      | `message`                                                                                               | 系统信息 / 会话分隔符 |
 | `reasoning`   | `ReasoningMessage` | `message`                                                                                               | AI 思考过程（可折叠） |

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

@@ -215,11 +215,16 @@ type ToolCall = {
   function: FunctionCall;
 };
 
+// 调用类型：不填等价于 function
+type FunctionCallType = 'function' | 'mcp' | 'skill';
+
 type FunctionCall = {
   name: string;
   arguments: string;
   description?: string;
   mcpName?: string;
+  // 决定 ToolcallRender 头部前缀（调用工具 / 调用 MCP / 读取 Skill）
+  type?: FunctionCallType;
 };
 
 // 示例

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

@@ -20,29 +20,29 @@
 
 > **能力域**：Agent 能力
 
-展示 AI 调用外部工具/函数过程与结果的渲染组件。由**可折叠头部**和**详情面板**组成，根据 `status` 自动切换颜色和状态文案，支持 MCP 调用识别和内联结果展示。
+展示 AI 调用外部工具 / MCP / Skill 过程与结果的渲染组件。由**单行可折叠头部**和**详情面板**组成：头部是一段弱化的灰色文本（`#979ba5`），按调用类型给出前缀，进行中用文字渐变闪动表示、结束后在工具名右侧补一段状态与耗时；详情面板默认折叠。
 
 ## 组件结构
 
 ```
-.ai-toolcall-render
-├── .ai-toolcall-render-header（高 40px，class="toolcall-status-{status}"）
-│   ├── ArrowRightIcon（14×14px，点击切换折叠；默认 rotate(0deg)，展开后 rotate(90deg)）
-│   ├── "调用工具：" / "调用 MCP："（有 mcpName 时）
-│   ├── .toolcall-header-title（工具名，overflow-tips 溢出截断）
-│   └── .toolcall-status-title
-│         ├── Loading（pending / streaming）
-│         ├── BkFlowSuccessIcon（success / complete / completed）
-│         ├── BkFlowFailedIcon（error）
-│         ├── 状态文案（调用中 / 调用成功 / 调用失败）
-│         └── .toolcall-duration（耗时，如 "(1.2s)"）
+.ai-toolcall-render（font-size: 12px，line-height: 20px）
+├── .ai-toolcall-render-header（单行，整行可点击切换折叠；class="is-expanded" 表示已展开）
+│   ├── ToolCallIcon（.ai-toolcall-icon，16×16px）
+│   ├── .toolcall-header-text（内联文本块，溢出截断 + overflow-tips）
+│   │     ├── .toolcall-header-title（前缀 + HighlightKeyword(工具名)）
+│   │     │     └── .is-loading（进行中，渐变光带闪动）
+│   │     └── .toolcall-header-status（v-if 有状态词；括号与耗时为弱显示）
+│   │           └── .toolcall-header-result（.is-success #2caf5e / .is-error #ea3636）
+│   └── ChevronRightIcon（.ai-chevron-right-icon，10×10px；v-if 非进行中，展开时 rotate(90deg)）
 │
-└── .ai-toolcall-render-content（v-show，默认折叠）
+└── .ai-toolcall-render-content（v-show，默认折叠，子项 gap: 8px）
       ├── DescPanel（title="描述"，desc=function.description）← 始终渲染
       ├── DescPanel（title="参数"，desc=function.arguments）← 始终渲染
       └── ToolMessage（v-if="toolCall?.toolMessage"）← 有结果时渲染
 ```
 
+> **头部悬停/展开反馈**：头部默认 `#979ba5`；`:hover` 或 `.is-expanded` 时，`ToolCallIcon` 与非闪动态的工具名变为 `#313238`，展开态的箭头同样变为 `#313238`。头部不再有背景色与边框（旧版的 `$toolcallStatusMap` 状态底色已随重构移除）。
+
 ## 基础用法
 
 ```vue
@@ -78,19 +78,49 @@
 
 ## 调用状态
 
-`status` prop 同时控制头部的 CSS class（`toolcall-status-{status}`）、背景/边框颜色、状态文案和状态图标：
+组件内部把 `status` 归一为**成功 / 失败 / 进行中**三态，不再逐个 status 匹配底色：
+
+```typescript
+isSuccess = [complete, completed, success].includes(status);
+isError = status === 'error' || !!toolCall?.toolMessage?.error; // toolMessage.error 可独立判定失败
+isPending = !isSuccess && !isError; // 其余（含 pending / streaming / stop / undefined）统一视为进行中
+```
+
+| 归一状态 | 命中条件                                             | 头部渲染                                                       |
+| -------- | ---------------------------------------------------- | -------------------------------------------------------------- |
+| 进行中   | 非成功且非失败（含未传 `status`）                    | 前缀替换为「正在调用」（Skill 为「正在读取」），标题带 `is-loading` 闪动，无状态段、无箭头 |
+| 成功     | `complete` / `completed` / `success`                 | 状态段 `( 成功 )`，状态词 `#2caf5e`                            |
+| 失败     | `status === 'error'` **或** `toolMessage.error` 为真 | 状态段 `( 失败 )`，状态词 `#ea3636`                            |
+
+关于状态段的三个细节：
 
-| `status`                              | 状态文案 | 背景色            | 边框色    | 状态图标            |
-| ------------------------------------- | -------- | ----------------- | --------- | ------------------- |
-| `pending` / `streaming`               | 调用中   | `#fafbfd`         | `#dcdee5` | `Loading`           |
-| `complete` / `completed` / `success`  | 调用成功 | `#ebfaf0`         | `#a1e3ba` | `BkFlowSuccessIcon` |
-| `error`                               | 调用失败 | `#fff0f0`         | `#f8b4b4` | `BkFlowFailedIcon`  |
-| 其他 / `undefined`                    | 调用中   | —（无匹配 class） | —         | —                   |
+- **只有状态词着色**：`.toolcall-header-result` 只包住「成功 / 失败」，括号与耗时留在 `.toolcall-header-status` 内保持弱显示
+- **括号写法**：头部渲染用半角括号并在两侧补 ` ` 撑开间距；`overflow-tips` 气泡里的纯文本用全角括号，形如 `调用工具 search（成功，耗时：1.2s）`
+- **失败优先**：`toolMessage.error` 有值时即便 `status` 是成功态也判为失败
 
-> **说明**：`statusTitle` 将 `Completed`（`completed`）与 `Complete` / `Success` 一并视为成功；主题 `$toolcallStatusMap` 同步提供 `completed` 色值。`default` 与 `case Pending` 共享「调用中」文案，`streaming` 与未知 status 命中 `default`。状态图标互斥：`pending` / `streaming` 显示 `Loading`；`success` / `complete` / `completed` 显示 `BkFlowSuccessIcon`；`error` 显示 `BkFlowFailedIcon`。
+进行中的「文字 loading」由 CSS 实现：`.toolcall-header-title.is-loading` 用 `linear-gradient` + `background-clip: text` 让一条光带以 `1.8s linear infinite` 循环扫过文字；`prefers-reduced-motion: reduce` 下自动关闭动画。
 
 **三种状态对比**
 
+## 调用类型前缀
+
+非进行中态的前缀由 `function.type` 决定；进行中态工具 / MCP 显示「正在调用」，Skill 显示「正在读取」：
+
+| `function.type`          | 前缀        | 说明                                     |
+| ------------------------ | ----------- | ---------------------------------------- |
+| `'function'` / 不传      | 调用工具    | 普通函数调用                             |
+| `'mcp'`                  | 调用 MCP    | MCP 调用，通常同时带 `mcpName`           |
+| `'skill'`                | 读取 Skill  | Skill 读取                               |
+
+```typescript
+const callType = fn?.type ?? (fn?.mcpName ? 'mcp' : 'function');
+```
+
+- **旧数据兼容**：未下发 `type` 时，有 `mcpName` 仍按 MCP 判定，历史消息展示不变
+- **`type` 优先**：显式 `type: 'function'` 不会被 `mcpName` 覆盖回 MCP，但标题仍是 `{mcpName} / {name}`
+
+**三种前缀对比**
+
 ## 工具标题（toolTitle）
 
 头部标题的计算规则：
@@ -100,16 +130,20 @@
 无 mcpName → function.name || toolCall.id
 ```
 
-`function.name` 为空字符串时，自动回退到 `toolCall.id` 作为标题。标题超出容器宽度时截断并配备 overflow-tips。
+`function.name` 为空字符串时，自动回退到 `toolCall.id` 作为标题。前缀、标题与状态段同处一个内联文本块 `.toolcall-header-text`，整体超出容器宽度时统一截断，并由 overflow-tips 展示完整文案。
 
 ## 折叠/展开详情面板
 
-详情面板**默认折叠**，点击头部左侧的 **箭头图标**（14×14px 可点区域，非整行）切换折叠状态。折叠状态由 `collapsed`（默认 `true`）和 `superCollapsed` 两个 `shallowRef` 共同管理，不暴露为 prop/v-model。
+详情面板**默认折叠**，点击**整行头部**切换折叠状态（旧版仅箭头可点）。折叠状态由 `collapsed`（默认 `true`）和 `superCollapsed` 两个 `shallowRef` 管理，不暴露为 prop/v-model。
 
-| 折叠状态     | 箭头旋转角度            | 详情面板      |
-| ------------ | ----------------------- | ------------- |
-| 折叠（默认） | `rotate(0deg)`（朝右）  | `v-show` 隐藏 |
-| 展开         | `rotate(90deg)`（朝下） | 可见          |
+| 折叠状态     | 箭头                                | 头部 class    | 详情面板      |
+| ------------ | ----------------------------------- | ------------- | ------------- |
+| 折叠（默认） | `ChevronRightIcon` 朝右             | —             | `v-show` 隐藏 |
+| 展开         | `rotate(90deg)` 朝下，颜色 `#313238` | `is-expanded` | 可见          |
+
+> **进行中不渲染箭头**：`isPending` 为真时箭头隐藏（此时通常还没有结果可看），但头部点击仍会切换详情面板。
+>
+> **关键词联动**：接入 `useKeywordMatch` 后，若上层正在搜索关键词且用户未手动点过头部（`superCollapsed` 为 `null`），面板会按「命中关键词则展开」自动切换；用户一旦点击，`superCollapsed` 接管并固定为手动选择的状态。
 
 详情面板由三块区域构成：
 
@@ -133,6 +167,8 @@ durationDisplay = formatDuration(props.duration || toolCall?.toolMessage?.durati
 | 未传 `duration`，toolMessage 有 `duration` | 使用 `toolMessage.duration` |
 | 两者均无                                   | 不显示耗时                  |
 
+耗时不再单独占一个元素，而是拼进状态段：有耗时时渲染为 `( 成功，耗时：1.2s )`，无耗时时只保留 `( 成功 )`。进行中态没有状态段，因此也不展示耗时。
+
 ```vue
 <!-- 方式一：直接传 duration prop（优先） -->
 <ToolcallRender :tool-call="toolCall" status="complete" :duration="1200" />
@@ -156,32 +192,28 @@ const toolCallWithDuration: ToolCall = {
 };
 ```
 
-## MCP 工具调用
+## MCP 调用
 
-`function.mcpName` 有值时：
-
-- 头部文案从 **"调用工具："** 自动切换为 **"调用 MCP："**
-- 标题格式变为 `{mcpName} / {functionName}`
+`function.type` 为 `'mcp'`（或旧数据仅有 `mcpName`）时，前缀为「调用 MCP」，标题格式变为 `{mcpName} / {functionName}`：
 
 ```typescript
 const mcpToolCall: ToolCall = {
   id: 'call_mcp_1',
   type: 'function',
   function: {
+    type: 'mcp', // ← 前缀显示「调用 MCP」；缺省时有 mcpName 也会兼容判定为 MCP
     name: 'query_table',
     arguments: JSON.stringify({ table: 'events', limit: 50 }),
     description: '通过 MCP 协议查询蓝鲸数据平台中的事件数据',
-    mcpName: 'bk-data-server', // ← 有值时头部显示"调用 MCP："
+    mcpName: 'bk-data-server',
   },
 };
-// 头部显示：调用 MCP：  bk-data-server / query_table
+// 头部显示：调用 MCP bk-data-server / query_table（成功，耗时：830ms）
 ```
 
-**渲染效果**
-
 ## 调用失败
 
-`toolMessage.error` 有值且 `content` 为空时，`ToolMessage` 内部展示错误信息（由 `content || error` 决定）。`status` 设为 `error` 控制头部红色样式：
+`toolMessage.error` 有值且 `content` 为空时，`ToolMessage` 内部展示错误信息（由 `content || error` 决定）。头部状态词是否红色由 `status === 'error'` **或** `toolMessage.error` 任一命中决定，因此下例即使不传 `status` 也会显示失败：
 
 ```typescript
 const failedToolCall: ToolCall = {
@@ -257,15 +289,17 @@ const assistantMessage = {
 </template>
 ```
 
+> **多条工具调用**：`AssistantMessage` 把 `toolCalls` 包在 `.ai-assistant-message-toolcalls` 容器内，条目之间固定 `8px` 间距，不受消息区 `12px` 间距影响。
+
 ## API
 
 ### Props
 
-| 属性名   | 类型            | 默认值 | 说明                                                                        |
-| -------- | --------------- | ------ | --------------------------------------------------------------------------- |
-| toolCall | `ToolCall`      | —      | 工具调用信息对象                                                            |
-| status   | `MessageStatus` | —      | 调用状态，控制头部颜色和状态文案；未传时 `default` 分支显示"调用中"         |
-| duration | `number`        | —      | 调用耗时（毫秒），优先于 `toolCall.toolMessage?.duration`；均无时不显示耗时 |
+| 属性名   | 类型            | 默认值 | 说明                                                                                |
+| -------- | --------------- | ------ | ----------------------------------------------------------------------------------- |
+| toolCall | `ToolCall`      | —      | 工具调用信息对象                                                                    |
+| status   | `MessageStatus` | —      | 调用状态，归一为成功 / 失败 / 进行中三态；未传时按进行中渲染（「正在调用」+ 闪动）  |
+| duration | `number`        | —      | 调用耗时（毫秒），优先于 `toolCall.toolMessage?.duration`；均无时状态段不展示耗时   |
 
 ## 类型定义
 
@@ -275,6 +309,7 @@ import {
   MessageContentType,
   type ToolCall,
   type FunctionCall,
+  type FunctionCallType,
   type ToolMessage,
 } from '@blueking/chat-x';
 
@@ -286,12 +321,16 @@ type ToolCall = {
   toolMessage?: Partial<ToolMessage>; // 有值时在详情面板底部内联渲染 ToolMessage
 };
 
+// FunctionCallType —— 调用类型
+type FunctionCallType = 'function' | 'mcp' | 'skill';
+
 // FunctionCall —— 函数调用描述
 type FunctionCall = {
   name: string; // 函数名；为空时标题 fallback 为 toolCall.id
   arguments: string; // 调用参数（通常为 JSON 字符串）
   description?: string; // 工具描述；为空时"描述"区块保留但内容为空白
-  mcpName?: string; // MCP 服务名；有值时头部改为"调用 MCP："，标题格式变为 "{mcpName} / {name}"
+  mcpName?: string; // MCP 服务名；有值时标题格式变为 "{mcpName} / {name}"，缺省 type 时兼容判定为 MCP
+  type?: FunctionCallType; // 调用类型，决定头部前缀；不传按 mcpName 兼容判定
 };
 
 // ToolMessage —— 工具返回消息