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

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

@@ -12,46 +12,60 @@
 <!-- FULL DOC -->
 
 # LoadingMessage 加载中消息
+
 ## 源码事实
 
 - **源码位置**：`src/components/chat-message/loading-message/loading-message.vue`
 - **能力域**：消息系统
 - **能力说明**：消息列表中的加载占位，默认使用 AiLoading，也支持默认插槽覆盖。
 
-> **能力域**：消息系统
+> **导出说明**：`LoadingMessage` **未**从包入口导出。消费方经 `MessageRender`（`role: 'loading'`）或由 `MessageContainer` 自动注入。下文 `LoadingMessageComp` 为文档站内部示例。
 
-加载等待状态组件，展示 AI 正在处理请求时的过渡动画。由旋转渐变环 + 脉冲星形图标（蓝→紫→粉渐变）和"请求中..."文案组成。支持通过默认插槽自定义加载文案。
+加载等待状态组件：`AiLoading`（18px）+ 默认文案「请求中...」。可通过默认插槽自定义文案。
 
-> **提示**：此组件通常**不需要手动使用**，`MessageContainer` 会在满足条件时自动注入。
+> **提示**：通常**不需要手动使用**，`MessageContainer` / `useMessageGroup` 会在满足条件时自动注入。
 
 ## 渲染效果
 
 ## 基础用法
 
-组件无 Props，直接引入渲染即可：
+组件无 Props。文档站内部示例：
+
+```vue
+<template>
+  <LoadingMessageComp />
+</template>
+```
+
+消费方经 `MessageRender`：
 
 ```vue
 <template>
-  <LoadingMessage />
+  <MessageRender
+    :message="{
+      id: 'loading',
+      messageId: '',
+      role: MessageRole.Loading,
+      content: '',
+      status: MessageStatus.Pending,
+    }"
+  />
 </template>
 
 <script setup lang="ts">
-  import { LoadingMessage } from '@blueking/chat-x';
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
 </script>
 ```
 
 ## 自定义加载文案
 
-通过默认插槽可覆盖默认的"请求中..."文案：
+通过默认插槽覆盖「请求中...」：
 
 ```vue
 <template>
-  <LoadingMessage>正在思考中，请稍候...</LoadingMessage>
+  <!-- 文档站内部示例 -->
+  <LoadingMessageComp>正在思考中，请稍候...</LoadingMessageComp>
 </template>
-
-<script setup lang="ts">
-  import { LoadingMessage } from '@blueking/chat-x';
-</script>
 ```
 
 ## 动画说明
@@ -67,15 +81,18 @@
 
 ## 在 MessageContainer 中的自动注入
 
-`MessageContainer` 在构建消息分组列表时，检测到**消息列表最后一条为用户消息**（`role === 'user'`）时，自动在末尾追加一个 Loading 消息组：
+`useMessageGroup` 构建分组时，若**最后一条为用户消息**且 **`renderMode !== RenderMode.Share`**，自动在末尾追加 Loading 组：
 
 ```typescript
-// MessageContainer 内部逻辑（简化）
-if (messages.at(-1)?.role === MessageRole.User) {
+// use-message-group.ts（简化）
+const shouldAppendLoading =
+  messages.at(-1)?.role === MessageRole.User && renderMode !== RenderMode.Share;
+
+if (shouldAppendLoading) {
   list.push({
     messages: [
       {
-        role: MessageRole.Loading, // 'loading'
+        role: MessageRole.Loading,
         content: '',
         status: MessageStatus.Pending,
         id: 'loading',
@@ -87,7 +104,8 @@ if (messages.at(-1)?.role === MessageRole.User) {
 }
 ```
 
-当下一条 AI 消息（`role: 'assistant'`）到来后，最后一条不再是用户消息，Loading 组自动消失。
+- 下一条 AI 消息到来后，末尾不再是 user，Loading 组自动消失
+- **分享预览**（`renderMode === RenderMode.Share`）**不会**注入 Loading，避免分享页出现「请求中」占位
 
 **触发示例**：
 
@@ -127,6 +145,7 @@ if (messages.at(-1)?.role === MessageRole.User) {
 - **默认插槽**：可通过默认插槽自定义加载文案，未传入时显示内置的 "请求中..."
 - **i18n 支持**：默认文案 "请求中..." 通过内置 `t()` 函数处理，英文环境自动显示 "Requesting..."
 - **选择模式**：`MessageContainer` 开启 `enableSelection` 时，Loading 消息组不显示复选框
+- **分享模式**：`renderMode === RenderMode.Share` 时不自动注入 Loading
 - **自动生命周期**：Loading 组随消息列表变化自动插入/移除，无需手动控制
 
 ## API

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

@@ -26,7 +26,7 @@
 - **消息分组**：将连续的非用户消息合并为一组，每组共享一个工具栏
 - **Tool 消息关联**：自动将 `role: 'tool'` 消息注入到对应 Assistant 消息的 toolCall 中
 - **Loading 自动注入**：末尾为用户消息时，自动追加 Loading 动画组
-- **滚动管理**：`messageStatus` 为流式、等待响应或请求中（`streaming` / `pending` / `fetching`）时显示「停止生成」，离开底部时显示「返回底部」；`renderMode` 为 `Share` 时不显示「停止生成」
+- **滚动管理**：`messageStatus` 为流式、等待响应或请求中（`streaming` / `pending` / `fetching`）时显示「停止生成」，离开底部时显示「返回底部」；`renderMode` 为 `Share` 时不显示「停止生成」。挂载时通过 `jumpToBottom()` 瞬时贴底，避免切换会话时从顶部平滑滚到底部的动画
 - **多选模式**：支持按消息组勾选，用户消息与 AI 回复联动选中
 
 ## 基础用法
@@ -124,10 +124,29 @@
   - `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
 
+## DOM 定位标识
+
+为方便业务方通过 `document.querySelector` 定位消息（埋点、自动化测试、外部滚动锚定等），渲染结构上固定输出两层标识：
+
+| 层级     | 选择器                                | 值                                                  |
+| -------- | ------------------------------------- | --------------------------------------------------- |
+| 消息组   | `.message-group[data-message-group-id]` | `MessageGroup.uid`（与外层 `id` 同值）              |
+| 单条消息 | `.ai-message-item[data-message-id]`   | `message.id`，缺失时回退 `message.uid`；两者都无则不输出该属性 |
+
+```js
+// 定位某条消息
+document.querySelector('[data-message-id="123"]');
+// 定位某个消息组下的全部消息
+document.querySelectorAll('[data-message-group-id="xxx"] [data-message-id]');
+```
+
+`.ai-message-item` 是 `MessageContainer` 统一包裹的容器，`#default` 插槽自定义渲染的消息同样被它包裹，因此无论用默认 `MessageRender` 还是自定义渲染，标识都一致存在。
+
 ## 等待响应（Loading 自动注入）
 
 当 `messages` 末尾为 `role: 'user'` 时，自动追加 Loading 消息组，展示 AI 正在处理的加载动画（`renderMode` 为 `Share` 时不追加，且 `MessageContainer` 会过滤 Loading 组）：
@@ -533,10 +552,11 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 | 按钮         | 显示条件                                                                                       | 点击行为               |
 | ------------ | ---------------------------------------------------------------------------------------------- | ---------------------- |
 | 「停止生成」 | `messageStatus` 为 `streaming`、`pending`、`fetching` 或 `stop-loading`（停止中 loading 态），且 `renderMode` 不为 `Share` | 触发 `@stop-streaming` |
-| 「返回底部」 | `debouncedShowScrollBottomBtn`（距底部 > 100px，且防抖 300ms 后才显示/隐藏）                     | 滚动到消息列表底部     |
+| 「返回底部」 | `debouncedShowScrollBottomBtn`（距底部 > 100px，且防抖 300ms 后才显示/隐藏）                     | 平滑滚动到消息列表底部（显式 `toScrollBottom('smooth')`） |
 
 > **防抖说明**：「返回底部」按钮的显隐使用 300ms 防抖，避免快速滚动时按钮频繁闪烁。隐藏时立即生效（无防抖），显示时延迟 300ms。
 
+> **首屏 / 切换会话贴底**：`MessageContainer` 挂载时若已有消息组，会立即调用 `jumpToBottom()`，并在下一帧再补一次，避免历史消息渲染过程中出现「从顶部滚到底部」的动画。流式输出场景下的小幅跟随仍由 markdown 挂载触发的 `toScrollBottom()`（距底较近时走 smooth）完成。
 ## API
 
 ### Props
@@ -613,32 +633,16 @@ enum MessageToolsStatus {
   Hidden = 'hidden',
 }
 
-// 消息角色
-enum MessageRole {
-  User = 'user',
-  Assistant = 'assistant',
-  Tool = 'tool',
-  Reasoning = 'reasoning',
-  Activity = 'activity',
-  Info = 'info',
-  Interrupt = 'interrupt',
-  Loading = 'loading',
-}
-
-// 消息状态
-enum MessageStatus {
-  Pending = 'pending',
-  Streaming = 'streaming',
-  Complete = 'complete',
-  Error = 'error',
-  Stop = 'stop',
-  Disabled = 'disabled',
-}
+// 消息角色 / 消息状态完整枚举见常量文档，勿在此维护副本
+// MessageRole、MessageStatus → ../../types/constants
 ```
 
+> `MessageRole` / `MessageStatus` 完整取值见 [常量枚举](../../types/constants)。
+
 ## 关联组件
 
 - [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

@@ -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`        | 消息内容     |
-| `status`  | `MessageStatus` | 当前消息状态 |
+| 参数      | 类型     | 说明                         |
+| --------- | -------- | ---------------------------- |
+| `content` | `string` | 消息内容（运行时保证）       |
 
-## 与 MessageContainer 配合
+## 与 MessageContainer / ChatContainer 配合
 
-在 `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） |
 
 ## 消息类型映射
 
@@ -305,34 +315,12 @@ slot 参数类型与 `AssistantMessage` 的 slot 保持一致（`Partial<Assista
 ```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',
-}
+// MessageRole / MessageStatus 完整枚举见 ../../types/constants
+// MessageToolsStatus：Disabled | Hidden（仅转发给 UserMessage）
 ```
 
+> `MessageRole` / `MessageStatus` 完整取值见 [常量枚举](../../types/constants)。
+
 ## 关联组件
 
 - [MessageContainer](/components/setup/message-container) — 内部按组调用以渲染每条消息

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` 全局配置