@blueking/chat-x 0.0.50 → 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

@@ -124,6 +124,7 @@
   - `renderMode === RenderMode.Share`（分享预览模式）
   - 消息组的 `pause` 为 `true`（来源于 `message.property?.extra?.pause`）
   - 多选模式（`enableSelection`）开启且消息组不是 Loading 类型
+- AI 消息组的时间通过 `MessageTools` 的 `#append` 插槽渲染在工具图标右侧，取值为组内**最后一条**带 `createdAt` 的消息（即本轮回答完成时间）；组内 `reasoning` / `activity` 等子消息不单独展示时间，全组都没有 `createdAt` 时不展示
 - `renderMode === RenderMode.Test` 时，工具栏会过滤掉「分享」按钮，其余正常
 - `renderMode === RenderMode.Share` 时，`message-group-messages` 自动添加 `message-group-enabled-selection` 类名（与 `enableSelection: true` 一致的多选视觉效果）
 - Loading 消息组的 `type` 是 `MessageRole.Loading`，不显示工具栏和多选 Checkbox
@@ -567,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` | 是否启用多选模式                                                                                                                         |
@@ -641,6 +643,7 @@ enum MessageToolsStatus {
 ## 关联组件
 
 - [MessageRender](/components/message/message-render) — 按组渲染每条消息时委托使用
+- [MessageTime](/components/feedback/message-time) — AI 消息组工具栏右侧的时间
 - [InterruptMessage 中断消息](/components/agent/interrupt-message) — `role: 'interrupt'` 的渲染与 `onInterruptResume` 透传
 - [ChatInput](/components/input/chat-input) — 常与输入区组合构成完整对话界面
 - [LoadingMessage](/components/message/loading-message) — 末尾为用户消息时自动追加加载组

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/message-time.md

@@ -0,0 +1,180 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+按 createdAt 展示消息时间，四档格式：今天 `12:00`、昨天 `昨天 12:00`、今年内更早 `3-12 12:00`、非今年 `2025-3-12 12:00`； 时区取 props.timezone，未传时回退 injectGlobalConfig().timezone（由 ChatContainer 的 timezone prop 注入），都没有则用浏览器时区； 无值或非法时间不渲染任何 DOM。通常通过 MessageTools 的 prepend / append 插槽使用。 源码位置：src/components/message-tools/message-time/message-time.vue。
+
+### 关联组件
+- **message-tools** — 通过 prepend / append 插槽嵌入工具栏
+- **user-message** — 用户消息在工具栏左侧展示时间
+- **message-container** — AI 消息组在工具栏右侧展示本轮回答时间
+
+---
+<!-- FULL DOC -->
+
+# MessageTime 消息时间
+
+## 源码事实
+
+- **源码位置**：`src/components/message-tools/message-time/message-time.vue`
+- **格式化工具**：`src/components/message-tools/message-time/format-message-time.ts`
+- **能力域**：工具与反馈
+- **能力说明**：按「今天 / 昨天 / 今年内 / 跨年」四档格式展示消息创建时间。
+
+> **能力域**：工具与反馈
+
+展示单条消息（或一组 AI 回答）的创建时间。组件本身只负责格式化与渲染一段文本，**位置由使用方决定**——项目内通过 `MessageTools` 的 `prepend` / `append` 插槽嵌入工具栏。
+
+## 格式规则
+
+时间按与「今天」的日历日差值分四档，同一档内时分固定 `HH:mm`（24 小时制，补零），月日**不补零**：
+
+| 档位         | 判定条件               | 输出示例        |
+| ------------ | ---------------------- | --------------- |
+| 今天         | 与今天同一日历日       | `12:00`         |
+| 昨天         | 与今天相差 1 个日历日  | `昨天 12:00`    |
+| 今年内更早   | 相差 ≥ 2 天且年份相同  | `3-12 12:00`    |
+| 非今年       | 年份不同               | `2025-3-12 12:00` |
+
+- 分档与展示取**同一时区**的日历日：既避免「昨天 23:59」与「今天 00:01」因毫秒差不足一天被判成同一天，也避免按浏览器时区分档、按配置时区显示时分导致的错位
+- `昨天` 走 `t('昨天')` 国际化，英文环境输出 `Yesterday 12:00`
+
+## 基础用法
+
+`createdAt` 接受 ISO 字符串或毫秒时间戳：
+
+```vue
+<template>
+  <MessageTime :created-at="message.createdAt" />
+</template>
+
+<script setup lang="ts">
+  import { MessageTime } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: 'user',
+    content: '你好',
+    status: 'completed',
+    createdAt: '2026-08-17T04:00:00.000Z',
+  };
+</script>
+```
+
+> **无值不渲染**：`createdAt` 为空、为空字符串或无法解析成合法时间时，组件不渲染任何 DOM（`v-if`），使用方无需额外判空。
+
+## 时区配置
+
+时区按以下优先级取值，均未配置时使用**浏览器时区**：
+
+```
+props.timezone
+  └─ 未传 → injectGlobalConfig()?.timezone（由 ChatContainer 的 timezone prop 注入）
+       └─ 未配置 → 浏览器时区
+```
+
+```vue
+<template>
+  <!-- 整个会话统一按北京时间展示 -->
+  <ChatContainer
+    :messages="messages"
+    timezone="Asia/Shanghai"
+  />
+</template>
+```
+
+```vue
+<template>
+  <!-- 单个实例覆盖全局配置 -->
+  <MessageTime
+    :created-at="message.createdAt"
+    timezone="UTC"
+  />
+</template>
+```
+
+- 取值为 [IANA 时区名](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)（如 `Asia/Shanghai`、`UTC`、`America/New_York`）
+- 传入非法时区名时回退到浏览器时区，不会导致渲染失败
+- 同一时区的 `Intl.DateTimeFormat` 实例内部有缓存，长会话中不会为每条消息重复构造
+
+## 在消息工具栏中的使用
+
+`MessageTools` 提供 `prepend`（工具图标左侧）与 `append`（工具图标右侧）两个插槽，项目内的时间位置即由此决定：
+
+| 场景         | 插槽      | 时间取值                                     |
+| ------------ | --------- | -------------------------------------------- |
+| 用户消息     | `prepend` | 该条消息的 `createdAt`                       |
+| AI 消息组    | `append`  | 组内**最后一条**带 `createdAt` 的消息，即本轮回答完成时间 |
+
+```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>
+```
+
+> 组内 `reasoning` / `activity` 等子消息不单独展示时间，一个 AI 回答组只显示一次。
+
+## API
+
+### Props
+
+| 属性名    | 类型               | 必填 | 默认值 | 说明                                                                 |
+| --------- | ------------------ | ---- | ------ | -------------------------------------------------------------------- |
+| createdAt | `number \| string` | 否   | —      | 消息创建时间，ISO 字符串或毫秒时间戳；无值或非法时不渲染             |
+| timezone  | `string`           | 否   | —      | IANA 时区名；优先于全局配置，两者都未配置时按浏览器时区展示          |
+
+### Events / Slots / Expose
+
+无。
+
+### 全局配置依赖
+
+通过 `injectGlobalConfig()` 读取 `timezone`。祖先需已调用 `useGlobalConfig()`（通常由 `ChatContainer` 的 `timezone` prop 注册）；无 Provider 时按浏览器时区展示。
+
+## 类型定义
+
+```typescript
+export type MessageTimeProps = {
+  createdAt?: number | string;
+  timezone?: string;
+};
+
+// 独立可用的格式化函数（组件内部使用，未从包入口导出）
+declare const formatMessageTime: (createdAt?: number | string, timezone?: string) => string;
+```
+
+## 样式说明
+
+```scss
+.ai-message-time {
+  flex: none;
+  font-size: var(--ai-font-size, 12px);
+  line-height: 16px;
+  color: $color-text-secondary;
+  white-space: nowrap;
+}
+```
+
+- 字号跟随 `--ai-font-size`（`ChatContainer` 的 `size` 档位），颜色使用次要文本语义色
+- `flex: none` + `nowrap` 保证在工具栏 flex 布局中不被压缩换行
+
+## 注意事项
+
+1. **时间来源**：`createdAt` 由消息层（`chat-helper`）写入 `BaseMessage`，组件不参与取数
+2. **不做相对时间**：不提供「几分钟前」这类相对描述，四档格式固定
+3. **空值语义**：不渲染而非渲染占位，工具栏侧的 `prepend` / `append` 包裹容器会因 `:empty` 收起，不留多余间距
+
+## 关联组件
+
+- [MessageTools](/components/feedback/message-tools) — 通过 `prepend` / `append` 插槽嵌入
+- [UserMessage](/components/message/user-message) — 用户消息时间位置
+- [MessageContainer](/components/setup/message-container) — AI 消息组时间位置
+- [useGlobalConfig](/composables/use-global-config) — `timezone` 全局配置