@blueking/chat-x 0.0.51 → 0.0.52-dev.2

package/skills/blueking-chat-x/references/components/message-loading.md

@@ -0,0 +1,118 @@
+# MessageLoading 品牌加载
+
+> 能力域：辅助能力 ｜ 导入：`import { MessageLoading } from '@blueking/chat-x'` ｜ since 1.0.0
+
+带品牌图标和逐字渐变动画的加载组件。 源码位置：src/components/message-loading/message-loading.vue。
+
+**关联**：loading-message（消息列表加载占位可选择使用品牌加载动效）、ai-loading（更轻量的三点加载动画）
+
+---
+
+# MessageLoading 品牌加载
+
+> **能力域**：辅助能力
+
+`MessageLoading` 是带蓝鲸品牌图标和逐字渐变动画的加载组件，用于展示 AI 正在思考、生成或执行任务的等待状态。组件默认显示品牌图标和“加载中...”文案，也支持通过插槽替换图标或文本。
+
+与 [AiLoading](./ai-loading.md) 相比，它更偏品牌化、文案化；适合较明显的等待区域，不适合嵌入很紧凑的按钮或状态点。
+
+## 源码事实
+
+- **源码位置**：`src/components/message-loading/message-loading.vue`
+- **能力说明**：带品牌图标和逐字渐变动画的加载组件。
+
+## 核心能力
+
+- **品牌图标动画**：默认使用 `AIBluekingIcon`，图标随 `duration` 做透明度和滤镜动画
+- **逐字渐变文本**：未传 `#text` 插槽时，将 `text` 拆成字符逐个渲染，并按 `stagger` 延迟播放
+- **可调尺寸和节奏**：通过 `iconSize`、`gap`、`duration`、`stagger` 控制图标尺寸、间距和动画速度
+- **插槽覆盖**：`#icon` 可替换图标，`#text` 可替换整段文本渲染
+- **无障碍降级**：遵循 `prefers-reduced-motion: reduce`，减少动画效果
+
+## 基础用法
+
+```vue
+<template>
+  <MessageLoading />
+</template>
+
+<script setup lang="ts">
+  import { MessageLoading } from '@blueking/chat-x';
+</script>
+```
+
+**渲染效果**
+
+## 自定义文案和尺寸
+
+```vue
+<template>
+  <MessageLoading
+    text="正在思考中..."
+    :icon-size="28"
+    :gap="10"
+    :duration="2"
+    :stagger="0.12"
+  />
+</template>
+```
+
+## 自定义插槽
+
+传入 `#text` 后，组件不再按字符拆分 `text` prop，而是直接渲染插槽内容；传入 `#icon` 可替换默认品牌图标。
+
+```vue
+<template>
+  <MessageLoading>
+    <template #icon>
+      <span class="custom-icon">AI</span>
+    </template>
+    <template #text>
+      正在生成巡检结论
+    </template>
+  </MessageLoading>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型     | 必填 | 默认值      | 说明                               |
+| -------- | -------- | ---- | ----------- | ---------------------------------- |
+| text     | `string` | 否   | `'加载中...'` | 逐字动画文案；使用 `#text` 时可不传 |
+| iconSize | `number` | 否   | `32`        | 默认图标边长，单位 px              |
+| gap      | `number` | 否   | `8`         | 图标与文字间距，单位 px            |
+| duration | `number` | 否   | `1.8`       | 单次动画循环时长，单位秒           |
+| stagger  | `number` | 否   | `0.135`     | 相邻字符动画延迟，单位秒           |
+
+### Emits
+
+- 无。
+
+### Slots
+
+| 插槽名 | 说明                     |
+| ------ | ------------------------ |
+| icon   | 自定义图标区域           |
+| text   | 自定义文本区域，覆盖逐字渲染 |
+
+### Expose
+
+- 无。
+
+## 样式与 attrs
+
+- 组件设置 `inheritAttrs: false`，会将外部 `class` 合并到根节点，并将除 `class` / `style` 外的 attrs 透传到根节点。
+- 外部对象形式的 `style` 会与 CSS 变量合并；字符串形式 `style` 不会参与合并。
+- 根节点使用 CSS 变量控制动画：`--ai-message-loading-duration`、`--ai-message-loading-stagger`、`--ai-message-loading-gap`。
+
+## 使用建议
+
+- 页面级或消息级等待态优先使用 `MessageLoading`；紧凑状态点优先使用 [AiLoading](./ai-loading.md)。
+- 需要自定义文本样式时优先使用 `#text` 插槽，避免只依赖全局覆盖内部 class。
+
+## 关联组件
+
+- [LoadingMessage](../message/loading-message.md) — 消息列表中的加载占位。
+- [AiLoading](./ai-loading.md) — 三点加载动画。

package/skills/blueking-chat-x/references/components/message-render.md

@@ -0,0 +1,327 @@
+# MessageRender 消息渲染器
+
+> 能力域：消息系统 ｜ 导入：`import { MessageRender } from '@blueking/chat-x'` ｜ since 0.0.20
+
+按 message.role 分发到用户、助手、工具、推理、活动、中断等消息组件。 源码位置：src/components/chat-message/message-render/message-render.vue。
+
+**关联**：message-container（在 MessageContainer 中按组调用以渲染每条消息）、assistant-message（role 为 assistant 时渲染 AI 回复与工具调用）、user-message（role 为 user 时渲染用户消息）、interrupt-message（role 为 interrupt 时渲染 InterruptMessageRender）
+
+---
+
+# MessageRender 消息渲染器
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/message-render/message-render.vue`
+- **能力域**：消息系统
+- **能力说明**：按 `message.role` 分发到用户、助手、工具、推理、活动、中断等消息组件。
+
+> **导出说明**：`MessageRender` **已**从 `@blueking/chat-x` 包入口导出，消费方可直接 import。下文 `MessageRenderComp` 为文档站相对路径 demo，与包入口行为一致。
+
+统一的消息渲染入口，通过 `message.role` 派发到对应子组件；由单个 `computed` 完成，无额外状态。
+
+## 渲染架构
+
+```
+MessageRender
+│
+├── props.message.role
+│     │
+│     ├── 'user'       → UserMessage（转发 message + onAction / onInputConfirm /
+│     │                               onShortcutConfirm / messageToolsStatus / tippyOptions）
+│     │
+│     ├── 'assistant'  → AssistantMessage（转发 message + default slot）
+│     │                    └── default slot 默认回退到 ContentRender
+│     │
+│     ├── 'info'       → InfoMessage（转发 message）
+│     ├── 'reasoning'  → ReasoningMessage（转发 message）
+│     ├── 'tool'       → ToolMessage（转发 message）
+│     ├── 'activity'   → ActivityMessage（转发 message + onInterruptResume）
+│     ├── 'loading'    → LoadingMessage（转发 message）
+│     ├── 'interrupt'  → InterruptMessageRender（转发 message + onInterruptResume）
+│     │
+│     └── 其他 / 未知   → null（不渲染任何内容）
+```
+
+> **重要**：`onAction`、`onInputConfirm`、`onShortcutConfirm`、`messageToolsStatus`、`tippyOptions` 这五个 prop **只转发给 `UserMessage`**。`AssistantMessage` 的工具栏由 `MessageContainer` 的 `MessageTools` 组件管理，`MessageRender` 不负责传递。
+
+## 基础用法
+
+```vue
+<template>
+  <MessageRender
+    :message="message"
+    :on-action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageRender, MessageRole, MessageStatus, type Message, type IToolBtn } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Assistant,
+    content: '你好！我是 AI 助手，有什么可以帮你的吗？',
+    status: MessageStatus.Complete,
+  };
+
+  const handleAction = async (tool: IToolBtn) => {
+    console.log('消息操作:', tool.id);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 各角色消息
+
+### 用户消息（user）
+
+`onAction`、`onInputConfirm`、`onShortcutConfirm`、`messageToolsStatus` 在此角色下生效。
+
+```vue
+<script setup lang="ts">
+  import { MessageRole, MessageStatus, type Message, type IToolBtn, type TagSchema } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.User,
+    content: '你好，请帮我解释一下什么是 Vue 3 的组合式 API',
+    status: MessageStatus.Complete,
+  };
+
+  const handleAction = async (tool: IToolBtn) => {
+    console.log('用户消息操作:', tool.id); // delete / copy 等
+  };
+  const handleInputConfirm = async (content: Message['content'], docSchema: TagSchema) => {
+    console.log('编辑确认:', content);
+  };
+  const handleShortcutConfirm = async (formModel: Record<string, unknown>) => {
+    console.log('快捷指令提交:', formModel);
+  };
+</script>
+```
+
+**渲染效果**
+
+### AI 助手消息（assistant）
+
+`message` 中的全部字段（含 `toolCalls`）直接透传给 `AssistantMessage`。
+
+```vue
+<script setup lang="ts">
+  import { MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '2',
+    messageId: '2',
+    role: MessageRole.Assistant,
+    content: `## Vue 3 组合式 API\n\n**组合式 API** 是 Vue 3 引入的一种新方式...`,
+    status: MessageStatus.Complete,
+  };
+</script>
+```
+
+**渲染效果**
+
+### 信息消息（info）
+
+`content` 为字符串或字符串数组，渲染居中虚线分隔条。
+
+### 推理消息（reasoning）
+
+`content` 为字符串数组，`duration` 为推理耗时（毫秒）。
+
+### 工具调用结果（tool）
+
+在 `MessageContainer` 中通常不独立渲染（被注入到 AssistantMessage），单独使用时如下：
+
+### 活动消息（activity）
+
+### 加载消息（loading）
+
+由 `MessageContainer` 自动注入，无需手动使用。
+
+## 消息状态
+
+### 流式输出（streaming）
+
+`status: 'streaming'` 时，默认回退的 `ContentRender` / `MarkdownContent` 会按流式规则补全未闭合语法；内容由外部逐步追加：
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MessageRole, MessageStatus, type Message } from '@blueking/chat-x';
+
+  const message = ref<Message>({
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Assistant,
+    content: '',
+    status: MessageStatus.Streaming,
+  });
+
+  // 模拟流式输出：逐步追加内容
+  const chunks = ['正在', '为你', '生成', '答案...'];
+  let i = 0;
+  const timer = setInterval(() => {
+    if (i < chunks.length) {
+      message.value.content += chunks[i++];
+    } else {
+      message.value.status = MessageStatus.Complete;
+      clearInterval(timer);
+    }
+  }, 300);
+</script>
+```
+
+**渲染效果**
+
+### 错误状态（error）
+
+```vue
+<script setup lang="ts">
+  import { MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Assistant,
+    content: '抱歉，生成回答时发生了错误，请重试。',
+    status: MessageStatus.Error,
+  };
+</script>
+```
+
+**渲染效果**
+
+## 自定义内容渲染（default slot）
+
+`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">
+    <template #default="{ content }">
+      <MyMarkdownRenderer
+        :content="content"
+        :streaming="message.status === 'streaming'"
+      />
+    </template>
+  </MessageRender>
+</template>
+```
+
+| 参数      | 类型     | 说明                         |
+| --------- | -------- | ---------------------------- |
+| `content` | `string` | 消息内容（运行时保证）       |
+
+## 与 MessageContainer / ChatContainer 配合
+
+自定义 `ChatContainer` 的 `#message` 时，插槽参数只有 `message` / `messageToolsStatus` / `onInterruptResume`。用户消息工具相关回调需由外层自行绑定透传，否则删除/编辑/复制会失效（AI 消息工具栏在 `MessageContainer` 内渲染，不受 `#message` 影响）：
+
+```vue
+<template>
+  <ChatContainer
+    :messages="messages"
+    :message-status="messageStatus"
+    :on-agent-action="handleAgentAction"
+    :on-user-action="handleUserAction"
+    :common-tippy-options="commonTippyOptions"
+  >
+    <template #message="{ message, messageToolsStatus, onInterruptResume }">
+      <MessageRender
+        :message="message"
+        :message-tools-status="messageToolsStatus"
+        :on-action="handleUserAction"
+        :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 }"
+        >
+          <MyCustomContent
+            :content="content"
+            :status="message.status"
+          />
+        </template>
+        <template #codeHeader="{ language, token }">
+          <MyCodeActions
+            :language="language"
+            :token="token"
+          />
+        </template>
+      </MessageRender>
+    </template>
+  </ChatContainer>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名             | 类型                                                                       | 默认值 | 说明                                              |
+| ------------------ | -------------------------------------------------------------------------- | ------ | ------------------------------------------------- |
+| 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`**      |
+| onInterruptResume  | `(payload: InterruptResume, interrupt?: Interrupt) => Promise<void>`         | —      | 中断 / FlowAgent 节点操作回调；转发给 `InterruptMessageRender` 与 `ActivityMessage`（后者仅 `flow_agent` 子组件消费） |
+| onShortcutConfirm  | `(formModel: Record<string, unknown>) => Promise<void>`                    | —      | 用户快捷指令提交回调；**仅转发给 `UserMessage`**  |
+| tippyOptions       | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | —      | 自定义 Tippy 配置；**仅转发给 `UserMessage`**     |
+
+### Slots
+
+| 插槽名           | 参数                                   | 说明                                                                                                    |
+| ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 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） |
+
+## 消息类型映射
+
+| `MessageRole` | 渲染组件           | prop 路由                                                                                               | 说明                  |
+| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------- | --------------------- |
+| `user`        | `UserMessage`      | `message` + `onAction` + `onInputConfirm` + `onShortcutConfirm` + `messageTools` + `messageToolsStatus` + `tippyOptions` | 用户发送的消息        |
+| `assistant`   | `AssistantMessage` | `message` + `default slot`                                                                              | AI 助手回复消息       |
+| `info`        | `InfoMessage`      | `message`                                                                                               | 系统信息 / 会话分隔符 |
+| `reasoning`   | `ReasoningMessage` | `message`                                                                                               | AI 思考过程（可折叠） |
+| `tool`        | `ToolMessage`      | `message`                                                                                               | 工具调用返回结果      |
+| `activity`    | `ActivityMessage`  | `message` + `onInterruptResume`                                                                         | 知识检索 / 引用文档 / FlowAgent 执行（节点重试 / 跳过） |
+| `loading`     | `LoadingMessage`   | `message`（字段被忽略，组件无 Props）                                                                   | 等待响应的加载占位    |
+| `interrupt`   | `InterruptMessageRender` | `message` + `onInterruptResume`                                                                         | human-in-the-loop 中断 |
+| 其他 / 未知   | —                  | —                                                                                                       | 返回 `null`，不渲染   |
+
+## 类型定义
+
+```typescript
+import { MessageRole, MessageStatus, MessageToolsStatus, type Message, type IToolBtn } from '@blueking/chat-x';
+
+// MessageRole / MessageStatus 完整枚举见 ../../types/constants
+// MessageToolsStatus：Disabled | Hidden（仅转发给 UserMessage）
+```
+
+> `MessageRole` / `MessageStatus` 完整取值见 [常量枚举](../../types/constants)。
+
+## 关联组件
+
+- [MessageContainer](/components/setup/message-container) — 内部按组调用以渲染每条消息
+- [AssistantMessage](/components/message/assistant-message) — assistant 角色派发目标
+- [UserMessage](/components/message/user-message) — user 角色派发目标
+- [InterruptMessage 中断消息](/components/agent/interrupt-message) — interrupt 角色派发目标
+- [ToolApprovalCard 审批卡片](/components/agent/tool-approval-card) — AI Dev 审批中断子卡片

package/skills/blueking-chat-x/references/components/message-time.md

@@ -0,0 +1,177 @@
+# MessageTime 消息时间
+
+> 能力域：工具与反馈 ｜ 导入：`import { MessageTime } from '@blueking/chat-x'` ｜ since 2.1.0
+
+按 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 消息组在工具栏右侧展示本轮回答时间）
+
+---
+
+# 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` 全局配置