@blueking/chat-x 0.0.50 → 0.0.51-beta.1

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

@@ -1,12 +1,13 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-消息悬浮工具栏，组合复制、删除、反馈等工具按钮。 源码位置：src/components/message-tools/message-tools.vue。
+消息悬浮工具栏，组合复制、删除、反馈等工具按钮；提供 prepend / append 两端插槽承载消息时间等附加内容。 源码位置：src/components/message-tools/message-tools.vue。
 
 ### 关联组件
 - **tool-btn** — 普通工具项由 ToolBtn 渲染
 - **user-feedback** — like/unlike 时弹出反馈表单
 - **delete-tool** — id 为 delete 时替换为带确认的删除按钮
+- **message-time** — 通过 prepend / append 插槽嵌入消息时间
 
 ---
 <!-- FULL DOC -->
@@ -20,22 +21,22 @@
 
 > **能力域**：工具与反馈
 
-AI 消息的操作工具栏组件，由**左侧消息工具区**和**右侧更新工具区**两部分组成，中间以分隔线分隔。仅 `like` / `unlike` 按钮会弹出反馈表单（`UserFeedback`），其余按钮直接触发 `onAction`。
+AI 消息的操作工具栏组件，由**左侧消息工具区**和**右侧更新工具区**两部分组成，中间以分隔线分隔；两端另有 `prepend` / `append` 插槽用于挂载消息时间等附加内容。仅 `like` / `unlike` 按钮会弹出反馈表单（`UserFeedback`），其余按钮直接触发 `onAction`。
 
 ## 组件结构
 
 ```
-┌─────────────────────────────────────────────────────┐
-│  .ai-message-tools-container                           │
-│  ┌─────────────────────┐  │  ┌───────────────────┐ │
-│  │  messageTools        │  │  │  updateTools      │ │
-│  │  copy cite rebuild…  │  │  │  like unlike del  │ │
-│  └─────────────────────┘  │  └───────────────────┘ │
-│             左侧区域      分隔线   右侧区域          │
-└─────────────────────────────────────────────────────┘
+┌───────────────────────────────────────────────────────────────────────┐
+│  .ai-message-tools-container（display: flex，gap: 4px）                 │
+│  ┌────────┐  ┌─────────────────────┐  │  ┌───────────────┐  ┌───────┐ │
+│  │#prepend│  │  messageTools        │  │  │  updateTools  │  │#append│ │
+│  │        │  │  copy cite rebuild…  │  │  │ like unlike…  │  │       │ │
+│  └────────┘  └─────────────────────┘  │  └───────────────┘  └───────┘ │
+│    插槽区          左侧区域         分隔线    右侧区域          插槽区   │
+└───────────────────────────────────────────────────────────────────────┘
 ```
 
-- 分隔线（`.ai-divider`）仅在 `updateTools` 非空时显示
+- 分隔线（`.ai-divider`）与**右侧更新工具区**均仅在 `updateTools` 非空时渲染
 - `updateTools` 中 `id` 为 `like` / `unlike` 的按钮被 `Tippy` 弹窗包裹，点击后展示 `UserFeedback` 反馈表单
 - `updateTools` 中 `id` 为 `delete` 的按钮使用 `DeleteTool` 组件，点击后展示**确认删除弹窗**（含"删除"/"取消"按钮），确认后触发 `onAction`
 - `updateTools` 中其他按钮直接触发 `onAction`，不弹表单
@@ -224,6 +225,32 @@ const CONST_UPDATE_TOOLS = [
 
 **渲染效果**
 
+## 两端插槽（prepend / append）
+
+`prepend`（工具图标左侧）与 `append`（工具图标右侧）用于在工具栏两端挂载附加内容，项目内用于放置 [MessageTime 消息时间](/components/feedback/message-time)：
+
+| 场景      | 使用插槽  | 效果                                    |
+| --------- | --------- | --------------------------------------- |
+| 用户消息  | `prepend` | 时间显示在工具图标左侧                  |
+| AI 消息组 | `append`  | 时间显示在工具图标右侧                  |
+
+```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>
+```
+
+- 插槽包裹容器（`.ai-message-tools-prepend` / `.ai-message-tools-append`）仅在对应插槽传入时渲染
+- 插槽内容为空时（如消息无 `createdAt`，`MessageTime` 不渲染任何 DOM），包裹容器命中 `:empty` 被收起，不会留下多余间距
+
 ## 工具栏状态控制
 
 `messageToolsStatus` 控制工具栏整体状态：
@@ -357,6 +384,13 @@ const CONST_UPDATE_TOOLS = [
 | -------- | ------------------------------------------------------------- | ------------------------------------------ |
 | feedback | `(tool: IToolBtn, reasonList: string[], otherReason: string)` | 用户在反馈表单点击"提交"后触发（not 取消） |
 
+### Slots
+
+| 插槽名  | 作用域参数 | 说明                                             |
+| ------- | ---------- | ------------------------------------------------ |
+| prepend | —          | 工具图标左侧的附加内容，如用户消息的时间         |
+| append  | —          | 工具图标右侧的附加内容，如 AI 消息组的时间       |
+
 ## 类型定义
 
 ```typescript
@@ -382,4 +416,5 @@ enum MessageToolsStatus {
 
 - [ToolBtn](/components/feedback/tool-btn) — 单项工具按钮
 - [UserFeedback](/components/feedback/user-feedback) — 点赞/踩反馈面板
-- [DeleteTool](/components/feedback/delete-tool) — 删除二次确认
+- [DeleteTool](/components/feedback/delete-tool) — 删除二次确认
+- [MessageTime](/components/feedback/message-time) — 两端插槽内的消息时间

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

@@ -54,6 +54,10 @@ interface BaseMessage<T extends MessageType, C = string> {
   // 消息名称（可选）
   name?: string;
 
+  // 可选：消息创建时间，ISO 字符串或毫秒时间戳，由消息层（chat-helper）写入
+  // 用于 MessageTime 展示；缺省时不展示时间
+  createdAt?: number | string;
+
   // 消息属性（可选）
   property?: {
     extra?: {
@@ -211,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 —— 工具返回消息

package/dist/mcp/generated/docs/use-artifact-preview.md

@@ -75,32 +75,30 @@ const { addCustomTab, ensureCustomTab, removeCustomTab } = useCustomTabProvider(
 // 会话级文件产物聚合已内聚在 useMessageGroup，直接消费
 const { sessionArtifacts } = useMessageGroup({ keyword, messages, selectedUserMessages });
 
+const FILE_ARTIFACT_TAB = {
+  closable: false,
+  label: t('文件产物'),
+  name: FILE_ARTIFACT_TAB_NAME,
+  order: -1,
+};
+
+// 常驻挂载：不随产物有无增删，无产物时由面板展示空态
+ensureCustomTab(FILE_ARTIFACT_TAB);
+
 const { activeArtifactId, setActiveArtifactId } = useArtifactPreviewProvider({
   getOnArtifactClick: () => props.onArtifactClick,
   // 点击文件卡片：展开侧栏并选中「文件产物」Tab
   onOpen: () => {
-    addCustomTab({
-      closable: false,
-      label: t('文件产物'),
-      name: FILE_ARTIFACT_TAB_NAME,
-      order: -1,
-    });
+    addCustomTab(FILE_ARTIFACT_TAB);
   },
 });
 
-// 有产物时静默挂上 Tab（不抢焦点）；无产物时清理
+// 仅维护命中态：无产物清空，命中项失效时回落到第一个
 watch(sessionArtifacts, list => {
   if (!list.length) {
-    removeCustomTab(FILE_ARTIFACT_TAB_NAME);
     setActiveArtifactId('');
     return;
   }
-  ensureCustomTab({
-    closable: false,
-    label: t('文件产物'),
-    name: FILE_ARTIFACT_TAB_NAME,
-    order: -1,
-  });
   if (!list.some(item => item.outputId === activeArtifactId.value)) {
     setActiveArtifactId(list[0].outputId);
   }
@@ -211,8 +209,12 @@ ArtifactFileCard（点击）
                  └─ FileArtifactPanel（列表 + 下载头，@select → setActiveArtifactId）
                       └─ ArtifactPreviewHost（loader + 分类型 renderer）
 
-sessionArtifacts 变化（有产物）
-  └─ ensureCustomTab(FILE_ARTIFACT_TAB_NAME) 静默挂上，不抢当前选中（如执行情况）
+容器初始化
+  └─ ensureCustomTab(FILE_ARTIFACT_TAB_NAME) 常驻挂上（不展开侧栏）；因 order:-1 排在首位，
+     未主动切换过 Tab 时会成为默认选中面板；无产物时由面板展示整块空态
+
+sessionArtifacts 变化
+  └─ 仅维护命中态（无产物清空，命中项失效回落第一个）；不增删 Tab
 ```
 
 分类型预览策略见 [FileArtifactPanel 预览机制](../components/message/file-artifact-panel#预览机制)。
@@ -222,7 +224,7 @@ sessionArtifacts 变化（有产物）
 - **职责单一**：composable 不直接调用 `useCustomTab`，侧栏 Tab 打开逻辑由 `onOpen` 注入；也不做正文 fetch / iframe 渲染
 - **ShallowRef 优先**：`activeArtifactId` 使用 `shallowRef`，避免不必要的深层响应式开销
 - **Consumer 兜底**：`useArtifactPreviewConsumer` 无 Provider 时返回 `undefined`，文件卡片在无容器上下文时自动不可点击
-- **与 useCustomTab 协作**：点击卡片走 `addCustomTab`（展开 + 选中）；会话已有产物时走 `ensureCustomTab`（只挂载，不抢焦点）；无文件产物时由容器 `removeCustomTab` 清理
+- **与 useCustomTab 协作**：点击卡片走 `addCustomTab`（展开 + 选中）；容器初始化时走 `ensureCustomTab` 常驻挂载（不展开；因 `order: -1` 在未主动切换前会成为默认选中），无产物也不移除，由面板展示空态
 
 ## 关联组件
 

package/dist/mcp/generated/docs/use-custom-tab.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/ensure/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不切换选中；addCustomTab 会展开并选中。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。
+useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/ensure/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据、可选 collapsed 注入受控折叠态 ref。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不主动切换选中；addCustomTab 会展开并选中。 未被主动切换过时，选中态默认跟随 Tab 栏首位（order 最小），如常驻的「文件产物」。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。
 
 ### 关联组件
 - **chat-container** — Provider 与侧栏 Tab 主场景
@@ -21,6 +21,8 @@ Provider/Consumer 模式的自定义 Tab 管理，用于 `ChatContainer` 侧边
 
 ```typescript
 function useCustomTabProvider<T extends Record<string, unknown>>(options: {
+  // 侧栏折叠态；由容器传入受控 ref（如 ChatContainer 的 v-model:asideCollapsed），缺省内部自持
+  collapsed?: Ref<boolean>;
   // 执行情况 Tab 是否展示，缺省 true；传 getter 以保持响应式
   executionTabVisible?: () => boolean | undefined;
   onTabChange?: (tab: CustomTab<T>) => void;
@@ -28,7 +30,7 @@ function useCustomTabProvider<T extends Record<string, unknown>>(options: {
   tabs: ShallowRef<CustomTab<T>[]>;
   displayTabs: ComputedRef<CustomTab<T>[]>;
   selectedTab: Ref<CustomTab<T>>;
-  isCollapse: ShallowRef<boolean>;
+  isCollapse: Ref<boolean>;
   addCustomTab: (tab: CustomTab<T>) => void;
   ensureCustomTab: (tab: CustomTab<T>) => void;
   removeCustomTab: (tabName: string) => void;
@@ -88,7 +90,7 @@ tabManager?.addCustomTab({
   },
 });
 
-// 仅确保 Tab 存在（不展开、不切换选中）—— 如侧栏已因执行情况打开时同步挂上文件产物
+// 仅确保 Tab 存在（不展开、不切换选中）—— 如常驻挂上文件产物 Tab
 tabManager?.ensureCustomTab({
   name: 'file-artifact',
   label: '文件产物',
@@ -114,10 +116,10 @@ tabManager?.removeCustomTab('node-detail-123');
 | --------------- | --------------------------- | ------------------------------------------------- |
 | tabs            | `ShallowRef<CustomTab[]>`   | 所有 Tab 列表（含默认的执行情况 Tab，保留隐藏项） |
 | displayTabs     | `ComputedRef<CustomTab[]>`  | Tab 栏实际展示列表：过滤 `visible === false`，按 `order` 升序稳定排序 |
-| selectedTab     | `Ref<CustomTab>`            | 当前选中的 Tab；选中项被隐藏时自动回退到首个可见 Tab |
-| isCollapse      | `ShallowRef<boolean>`       | 侧边栏折叠状态；`addCustomTab` 时自动设为 `false` |
+| selectedTab     | `Ref<CustomTab>`            | 当前选中的 Tab；未被主动切换过时跟随 Tab 栏首位，选中项被隐藏时自动回退到首个可见 Tab |
+| isCollapse      | `Ref<boolean>`              | 侧边栏折叠状态；传入 `collapsed` 时即该受控 ref（读写都作用于外部），否则为内部状态；`addCustomTab` 时自动设为 `false` |
 | addCustomTab    | `(tab: CustomTab) => void`  | 添加/合并 Tab，**展开侧栏并选中**目标 Tab |
-| ensureCustomTab | `(tab: CustomTab) => void`  | 添加/合并 Tab，**不展开、不切换选中**；用于静默挂载（如文件产物） |
+| ensureCustomTab | `(tab: CustomTab) => void`  | 添加/合并 Tab，**不展开、不主动切换选中**；用于常驻挂载（如文件产物） |
 | removeCustomTab | `(tabName: string) => void` | 移除指定 Tab                                      |
 | selectCustomTab | `(tab: CustomTab) => void`  | 切换到指定 Tab，触发 `onTabChange` 回调           |
 | resetCustomTab  | `() => void`                  | 重置为仅保留「执行情况」Tab、折叠侧栏并选中默认 Tab；`ChatContainer` 在卸载时调用，避免残留自定义 Tab |
@@ -147,9 +149,11 @@ interface CustomTab<T = Record<string, unknown>> {
 - 排序为稳定排序，`order` 相同的 Tab 保持插入先后顺序
 - 选中的 Tab 被配置隐藏时，内容不再渲染，自动切换到首个可见 Tab
 - `addCustomTab` 同时展开侧边栏（`isCollapse = false`）并在 `nextTick` 后自动选中目标 Tab；同名 Tab 合并更新
-- `ensureCustomTab` 与 `addCustomTab` 共用合并逻辑，但不改 `isCollapse`、不切换 `selectedTab`；适合「侧栏已打开时同步挂上文件产物」等场景
+- `ensureCustomTab` 与 `addCustomTab` 共用合并逻辑，但不改 `isCollapse`、自身不切换 `selectedTab`；适合「常驻挂载文件产物 Tab」等场景
+- 默认选中跟随 Tab 栏首位：只要没调用过 `selectCustomTab` / `addCustomTab`，挂上更靠前（`order` 更小）的 Tab 就会成为选中项，因此常驻的「文件产物」（`order: -1`）是侧栏默认面板；一旦主动切换过便不再跟随。`resetCustomTab` 会重置该标记
+- 折叠态支持受控：传入 `collapsed` 后 Provider 不再自持状态，内部展开动作直接写回该 ref，容器即可通过 `v-model` 把状态交给外部判断
 
 ## 关联组件
 
 - [ChatContainer](../components/setup/chat-container) — 侧栏 Tab 与自定义面板
-- [useArtifactPreview](./use-artifact-preview) — 文件产物 Tab：有产物时 `ensureCustomTab`，点击卡片时 `addCustomTab`
+- [useArtifactPreview](./use-artifact-preview) — 文件产物 Tab：初始化 `ensureCustomTab` 常驻挂载，点击卡片时 `addCustomTab`

package/dist/mcp/generated/docs/use-global-config.md

@@ -1,10 +1,11 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size 与 supportUpload； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。
+useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>、timezone?: ComputedRef<string | undefined>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size、supportUpload 与 timezone； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。
 
 ### 关联组件
 - **chat-container** — 根容器调用 useGlobalConfig 注入 supportUpload
+- **message-time** — 消息时间组件读取 timezone
 
 ---
 <!-- FULL DOC -->
@@ -13,7 +14,7 @@ useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、suppo
 
 > **分类**：composable
 
-在聊天容器根组件与子组件之间通过 Vue `provide` / `inject` 共享**全局展示相关配置**（当前包括字号主题档位 `size`、是否支持上传 `supportUpload`）。与 Teleport 插槽 ID 无关。
+在聊天容器根组件与子组件之间通过 Vue `provide` / `inject` 共享**全局展示相关配置**（当前包括字号主题档位 `size`、是否支持上传 `supportUpload`、消息时间时区 `timezone`）。与 Teleport 插槽 ID 无关。
 
 > 字号主题主要通过 `ChatContainer` 根节点的 `data-ai-size` 与 CSS 变量（`--ai-font-size` 等）生效；`GlobalConfig.size` 供后代在逻辑层读取当前档位，样式层无需逐组件传参。
 
@@ -25,10 +26,11 @@ ChatContainer（根）
   ├── useGlobalConfig({
   │     size: computed(() => props.size ?? 'small'),
   │     supportUpload: computed(() => props.supportUpload ?? false),
+  │     timezone: computed(() => props.timezone),
   │   })
-  │     └── provide(GLOBAL_CONFIG_TOKEN, { size, supportUpload })
+  │     └── provide(GLOBAL_CONFIG_TOKEN, { size, supportUpload, timezone })
   │
-  └── MessageContainer → … → UserMessage 等
+  └── MessageContainer → … → UserMessage / MessageTime 等
 
 UserMessage（后代）
   ├── injectGlobalConfig()
@@ -51,11 +53,14 @@ UserMessage（后代）
   const props = defineProps<{
     size?: 'normal' | 'small';
     supportUpload?: boolean;
+    timezone?: string;
   }>();
 
   useGlobalConfig({
     size: computed(() => props.size ?? 'small'),
     supportUpload: computed(() => props.supportUpload ?? false),
+    // 无默认值：未配置时由 MessageTime 回退到浏览器时区
+    timezone: computed(() => props.timezone),
   });
 </script>
 ```
@@ -88,11 +93,13 @@ export type AiSizeMode = 'normal' | 'small';
 export type GlobalConfig = {
   size?: ComputedRef<AiSizeMode>;
   supportUpload: ComputedRef<boolean>;
+  timezone?: ComputedRef<string | undefined>;
 };
 
 export function useGlobalConfig(options: GlobalConfig): {
   size?: ComputedRef<AiSizeMode>;
   supportUpload: ComputedRef<boolean>;
+  timezone?: ComputedRef<string | undefined>;
 };
 
 export function injectGlobalConfig(): GlobalConfig | undefined;
@@ -110,6 +117,7 @@ export function injectGlobalConfig(): GlobalConfig | undefined;
 | --------------- | ------------------------------------------------------------------------ |
 | `size`          | 可选。字号主题档位 `normal`（14px）/ `small`（12px），与 `ChatContainer.size` 对齐 |
 | `supportUpload` | 是否支持上传，与根容器 `ChatContainer` 的 `supportUpload` 等展示策略对齐 |
+| `timezone`      | 可选。消息时间展示所用的 IANA 时区名，与 `ChatContainer.timezone` 对齐；未配置时 `MessageTime` 按浏览器时区展示 |
 
 ### `useGlobalConfig(options)`
 
@@ -117,6 +125,7 @@ export function injectGlobalConfig(): GlobalConfig | undefined;
 | ----------------------- | ------------------------------------------------------------------------------------- |
 | `options.size`          | 可选。字号主题档位，建议使用 `computed(() => props.size ?? 'small')` 与根 props 同步 |
 | `options.supportUpload` | 是否支持上传，建议使用 `computed(() => props.supportUpload ?? false)` 与根 props 同步 |
+| `options.timezone`      | 可选。消息时间时区，建议使用 `computed(() => props.timezone)` 与根 props 同步；不设默认值，交由 `MessageTime` 回退浏览器时区 |
 
 - 调用后立即 `provide(GLOBAL_CONFIG_TOKEN, options)`。
 - 必须在具有组件实例上下文的 `setup` 中调用（与 Vue `provide` 要求一致）。
@@ -136,5 +145,6 @@ export function injectGlobalConfig(): GlobalConfig | undefined;
 
 ## 关联组件
 
-- [ChatContainer](../components/setup/chat-container) — 调用 `useGlobalConfig` 注入 `size` 与 `supportUpload`
+- [ChatContainer](../components/setup/chat-container) — 调用 `useGlobalConfig` 注入 `size`、`supportUpload` 与 `timezone`
+- [MessageTime](../components/feedback/message-time) — 读取 `timezone` 展示消息时间
 - [主题配置](../theme/theme) — `data-ai-size` 与 CSS 变量说明

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

@@ -6,6 +6,7 @@
 ### 关联组件
 - **message-render** — 由 MessageRender 在 role 为 user 时创建
 - **message-tools** — 消息工具栏交互与状态由 MessageTools 体系承载
+- **message-time** — createdAt 经工具栏 prepend 插槽展示
 - **message-container** — 嵌入列表时由 MessageContainer 管理分组与多选
 - **chat-input** — 编辑态普通消息使用 ChatInput
 
@@ -47,8 +48,11 @@
       v-if: messageToolsStatus !== 'hidden'
       visibility: hidden（默认）→ visible（:hover 时）
       tools: [copy, cite, edit, delete]，updateTools: []
+      #prepend slot → MessageTime（createdAt，工具图标左侧）
 ```
 
+> **时间随工具栏显隐**：时间位于工具栏内，与工具按钮共用 `visibility` 控制，因此同样在悬停消息时才可见。
+
 **编辑模式**（点击 `edit` 按钮后 `isEdit=true`）
 
 ```
@@ -311,6 +315,8 @@ binaryFiles 有值 → 进入编辑模式（editContent 可为空）
 | `edit`   | 编辑 | 切换 `isEdit=true`，进入编辑模式             |
 | `delete` | 删除 | 无内置行为，需通过 `onAction` 外部处理       |
 
+可通过 `messageTools` 按 id 覆盖/追加，`{ id: 'edit', hidden: true }` 可隐藏内置项。
+
 ```vue
 <!-- 经 MessageRender 控制工具栏状态 -->
 <MessageRender
@@ -356,7 +362,9 @@ binaryFiles 有值 → 进入编辑模式（editContent 可为空）
 | 属性名             | 类型                                                                                       | 说明                                                                      |
 | ------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
 | content            | `string \| InputContent[]`                                                                 | 消息内容，字符串或含 text/binary 的数组                                   |
+| createdAt          | `number \| string`                                                                         | 消息创建时间，经 `MessageTools` 的 `#prepend` 插槽交给 `MessageTime` 渲染在工具图标左侧；无值时不展示 |
 | property           | `{ extra?: MessageExtra; artifacts?: AIFileInfo[] }`                                       | 附加属性；本组件消费 `extra.cite` / `shortcut` / `context`                |
+| messageTools       | `IToolBtn[]`                                                                               | 自定义用户消息工具组；按 id 与 `CONST_USER_MESSAGE_TOOLS` 合并，`{ id, hidden: true }` 可隐藏 |
 | messageToolsStatus | `MessageToolsStatus`                                                                       | 工具按钮状态，`disabled` 禁用、`hidden` 从 DOM 移除                       |
 | onAction           | `MessageToolsProps['onAction']`                                                            | 工具回调；`copy`/`edit` 有内置行为，`cite`/`delete` 需外部处理            |
 | onInputConfirm     | `(content: UserMessage['content'], docSchema: TagSchema) => Promise<void>`                 | 普通消息编辑确认回调                                                      |
@@ -417,4 +425,5 @@ type MessageExtra = {
 
 - [MessageRender](/components/message/message-render) — user 角色由其实例化
 - [MessageTools](/components/feedback/message-tools) — 工具栏交互
+- [MessageTime](/components/feedback/message-time) — 工具栏左侧的消息时间
 - [MessageContainer](/components/setup/message-container) — 列表与多选容器

package/dist/mcp/generated/docs/user-question-card.md

@@ -188,6 +188,8 @@ const payload = buildSkipResumePayload(interrupt);
 
 `ChatContainer` 提供同名 `#interruptQuestion` slot，参数与 `#question` 一致，透传自输入区上方的 `UserQuestionCard`。
 
+> **跳过按钮禁用态**：`disabled` 时文字与图标同步变灰（`currentColor` / `#c4c6cc`）。
+
 ## API
 
 ### UserQuestionCard Props