@blueking/chat-x 0.0.49-beta.1 → 0.0.49-beta.11

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

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?: {
@@ -144,6 +148,9 @@ enum MessageStatus {
   // 已完成
   Complete = 'complete',
 
+  // 已完成（与 Complete 同义，兼容协议/后端返回的 completed）
+  Completed = 'completed',
+
   // 已禁用
   Disabled = 'disabled',
 
@@ -170,6 +177,8 @@ enum MessageStatus {
 }
 ```
 
+完整取值与说明见 [常量枚举 · MessageStatus](./constants#messagestatus)。
+
 ## 具体消息类型
 
 ### UserMessage

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

@@ -224,17 +224,10 @@ interface ReasoningMessage {
   duration?: number; // 推理耗时（毫秒）
   name?: string;
 }
-
-enum MessageStatus {
-  Pending = 'pending',
-  Streaming = 'streaming',
-  Complete = 'complete',
-  Success = 'success',
-  Error = 'error',
-  Stop = 'stop',
-}
 ```
 
+> `MessageStatus` 完整取值见 [常量枚举](../../types/constants)。本组件完成态识别 `complete` / `success`（与标题文案表一致）。
+
 ## 关联组件
 
 - [MessageRender](/components/message/message-render) — reasoning 角色由其实例化

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

@@ -31,7 +31,9 @@
 │   ├── "调用工具：" / "调用 MCP："（有 mcpName 时）
 │   ├── .toolcall-header-title（工具名，overflow-tips 溢出截断）
 │   └── .toolcall-status-title
-│         ├── Loading（仅 pending / streaming 时显示）
+│         ├── Loading（pending / streaming）
+│         ├── BkFlowSuccessIcon（success / complete / completed）
+│         ├── BkFlowFailedIcon（error）
 │         ├── 状态文案（调用中 / 调用成功 / 调用失败）
 │         └── .toolcall-duration（耗时，如 "(1.2s)"）
 │
@@ -76,16 +78,16 @@
 
 ## 调用状态
 
-`status` prop 同时控制头部的 CSS class（`toolcall-status-{status}`）、背景/边框颜色、状态文案和 Loading 动画：
+`status` prop 同时控制头部的 CSS class（`toolcall-status-{status}`）、背景/边框颜色、状态文案和状态图标：
 
-| `status`                | 状态文案 | 背景色            | 边框色    | Loading |
-| ----------------------- | -------- | ----------------- | --------- | ------- |
-| `pending` / `streaming` | 调用中   | `#fafbfd`         | `#dcdee5` | ✓       |
-| `complete` / `success`  | 调用成功 | `#ebfaf0`         | `#a1e3ba` | -       |
-| `error`                 | 调用失败 | `#fff0f0`         | `#f8b4b4` | -       |
-| 其他 / `undefined`      | 调用中   | —（无匹配 class） | —         | -       |
+| `status`                              | 状态文案 | 背景色            | 边框色    | 状态图标            |
+| ------------------------------------- | -------- | ----------------- | --------- | ------------------- |
+| `pending` / `streaming`               | 调用中   | `#fafbfd`         | `#dcdee5` | `Loading`           |
+| `complete` / `completed` / `success`  | 调用成功 | `#ebfaf0`         | `#a1e3ba` | `BkFlowSuccessIcon` |
+| `error`                               | 调用失败 | `#fff0f0`         | `#f8b4b4` | `BkFlowFailedIcon`  |
+| 其他 / `undefined`                    | 调用中   | —（无匹配 class） | —         | —                   |
 
-> **说明**：`statusTitle` 的 `switch` 语句中 `default` 与 `case Pending` 共享同一返回值，`streaming` 和未知 status 均命中 `default` 分支，显示"调用中"。Loading 动画由 `v-if="status === 'pending' || status === 'streaming'"` 单独控制。
+> **说明**：`statusTitle` 将 `Completed`（`completed`）与 `Complete` / `Success` 一并视为成功；主题 `$toolcallStatusMap` 同步提供 `completed` 色值。`default` 与 `case Pending` 共享「调用中」文案，`streaming` 与未知 status 命中 `default`。状态图标互斥：`pending` / `streaming` 显示 `Loading`；`success` / `complete` / `completed` 显示 `BkFlowSuccessIcon`；`error` 显示 `BkFlowFailedIcon`。
 
 **三种状态对比**
 
@@ -244,7 +246,13 @@ const assistantMessage = {
     v-for="toolCall in assistantMessage.toolCalls"
     :key="toolCall.id"
     :tool-call="toolCall"
-    :status="toolCall.toolMessage?.status ?? MessageStatus.Pending"
+    :status="
+      !toolCall.toolMessage
+        ? MessageStatus.Pending
+        : toolCall.toolMessage.error
+          ? MessageStatus.Error
+          : (toolCall.toolMessage.status ?? assistantMessage.status)
+    "
   />
 </template>
 ```

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useArtifactPreviewProvider 维护 activeArtifactId，openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（按 outputId 缓存 download_url / preview_url）； useArtifactPreviewConsumer 在后代注入同一套 API。buildArtifactId 用 messageUid#index#outputId 生成唯一 id。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。
+useArtifactPreviewProvider 维护 activeArtifactId（值为 outputId），openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（每次重新取链，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。
 
 ### 关联组件
 - **chat-container** — Provider 主场景，聚合 sessionArtifacts 并挂载 FileArtifactPanel
@@ -15,12 +15,12 @@ useArtifactPreviewProvider 维护 activeArtifactId，openPreview 命中文件并
 
 > **分类**：composable
 
-Provider/Consumer 模式的文件产物预览状态管理。Provider 在 `ChatContainer` 中创建，负责维护当前命中的文件 id；Consumer 在深层 `ArtifactFileCard` 中注入，用于点击卡片触发预览。
+Provider/Consumer 模式的文件产物预览状态管理。Provider 在 `ChatContainer` 中创建，负责维护当前命中的文件 `outputId`；Consumer 在深层 `ArtifactFileCard` 中注入，用于点击卡片触发预览。
 
 **职责边界**：
 
-- **本 composable**：维护「命中文件」与「URL 解析缓存」；打开侧栏 Tab（`addCustomTab`）由容器通过 `onOpen` 注入
-- **不在本 composable**：聚合会话文件列表、渲染预览面板、按类型 fetch 正文 / iframe 展示 —— 分别由 `useMessageGroup.sessionArtifacts`、`FileArtifactPanel`、内部 `ArtifactPreviewHost` + `useArtifactPreviewLoader` 承担
+- **本 composable**：维护「命中文件」与「URL 解析」（每次重新取链 + 并发去重）；打开侧栏 Tab（`addCustomTab`）由容器通过 `onOpen` 注入
+- **不在本 composable**：聚合会话文件列表、渲染预览面板、按类型 fetch 正文 / iframe 展示 —— 分别由 `useMessageGroup.sessionArtifacts`、`FileArtifactPanel`、内部 `ArtifactPreviewHost` + `useArtifactPreviewLoader` 承担（预览重载键为 `outputId:type`）
 
 ## 函数签名
 
@@ -31,7 +31,7 @@ function useArtifactPreviewProvider(options: {
   /** 读取业务侧异步取链回调（getter 保持对 props 变更敏感） */
   getOnArtifactClick?: () => OnArtifactClick | undefined;
   /** 命中文件后触发：由容器负责 addCustomTab + 展开侧栏 + 选中 Tab */
-  onOpen: (artifactId: string) => void;
+  onOpen: (outputId: string) => void;
 }): {
   activeArtifactId: ShallowRef<string>;
   canResolveArtifactUrl: ComputedRef<boolean>;
@@ -55,13 +55,6 @@ function useArtifactPreviewConsumer():
     };
 ```
 
-### buildArtifactId
-
-```typescript
-function buildArtifactId(messageUid: string, index: number, outputId: string): string;
-// => `${messageUid}#${index}#${outputId}`
-```
-
 ## 使用示例
 
 ### Provider（ChatContainer）
@@ -77,30 +70,39 @@ import {
 } from '@blueking/chat-x';
 import { t } from '@blueking/chat-x/lang';
 
-const { addCustomTab, removeCustomTab } = useCustomTabProvider({ /* ... */ });
+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;
   }
-});
+  if (!list.some(item => item.outputId === activeArtifactId.value)) {
+    setActiveArtifactId(list[0].outputId);
+  }
+}, { immediate: true });
 ```
 
 ### Consumer（ArtifactFileCard）
@@ -118,18 +120,14 @@ const handleCardClick = () => {
     props.onPreview(props.file);
     return;
   }
-  artifactPreview?.openPreview({
-    file: props.file,
-    index: props.index ?? 0,
-    messageUid: props.messageUid ?? '',
-  });
+  artifactPreview?.openPreview({ file: props.file });
 };
 ```
 
 ### 侧栏列表内切换命中文件
 
 ```typescript
-// FileArtifactPanel 列表点击 → emit select → 容器调用 setActiveArtifactId
+// FileArtifactPanel 列表点击 → emit select(outputId) → 容器调用 setActiveArtifactId
 // 右侧预览由面板内 ArtifactPreviewHost 消费 activeArtifact，自行取链并按类型渲染
 <FileArtifactPanel
   :active-id="activeArtifactId"
@@ -163,32 +161,27 @@ const onArtifactClick = async (file: AIFileInfo) => {
 
 | 属性/方法名         | 类型                                      | 说明                                                                 |
 | ------------------- | ----------------------------------------- | -------------------------------------------------------------------- |
-| activeArtifactId    | `ShallowRef<string>`                      | 当前命中的文件 id（`messageUid#index#outputId`）                     |
+| activeArtifactId    | `ShallowRef<string>`                      | 当前命中的文件 `outputId`                                            |
 | canResolveArtifactUrl | `ComputedRef<boolean>`                  | 是否具备异步取链能力（有 `onArtifactClick` 时为 true，下载按钮据此显隐） |
-| openPreview         | `(payload: OpenArtifactPreviewPayload) => void` | 由文件卡片触发：计算 id、更新命中态、调用 `onOpen`             |
-| resolveArtifactUrls | `(file: AIFileInfo) => Promise<ArtifactUrlResult>` | 调用 `onArtifactClick` 并按 `outputId` 缓存结果；并发请求去重 |
-| setActiveArtifactId | `(id: string) => void`                    | 直接设置命中文件 id；侧栏列表内切换选中时使用                        |
+| openPreview         | `(payload: OpenArtifactPreviewPayload) => void` | 由文件卡片触发：以 `file.outputId` 更新命中态、调用 `onOpen`   |
+| resolveArtifactUrls | `(file: AIFileInfo) => Promise<ArtifactUrlResult>` | 调用 `onArtifactClick` 取链；每次重新获取，不缓存；同文件并发去重 |
+| setActiveArtifactId | `(id: string) => void`                    | 直接设置命中文件 `outputId`；侧栏列表内切换选中时使用                |
 
 ## 类型定义
 
 ```typescript
 import type { AIFileInfo, ArtifactUrlResult, OnArtifactClick } from '@blueking/chat-x';
 
-/** 打开预览时的入参：文件 + 消息内下标 + 所属消息 uid */
+/** 打开预览时的入参 */
 type OpenArtifactPreviewPayload = {
   file: AIFileInfo;
-  index: number;
-  messageUid: string;
 };
 
 /**
- * 会话级文件产物：在 AIFileInfo 基础上补充命中所需的唯一 id 与所属消息。
- * 同一会话可能出现多个 AssistantMessage + 同名文件，文件名不可作唯一键。
+ * 会话级文件产物：以 outputId 为会话内唯一键（同 outputId 视为同一文件）。
+ * 拍平去重后即为 AIFileInfo，此处用别名标明语义。
  */
-type SessionArtifact = AIFileInfo & {
-  artifactId: string;
-  messageUid: string;
-};
+type SessionArtifact = AIFileInfo;
 
 /** onArtifactClick 返回值（snake_case） */
 type ArtifactUrlResult = {
@@ -197,28 +190,31 @@ type ArtifactUrlResult = {
 };
 ```
 
-## 唯一 id 规则
-
-同一会话可能存在多个 `AssistantMessage`，且不同消息里可能有同名文件，因此**文件名不可作为唯一键**。Provider 侧聚合与 Consumer 侧透传必须使用同一 `buildArtifactId` 规则：
+## 唯一键规则
 
-```typescript
-buildArtifactId('msg-a', 2, 'output-9'); // => 'msg-a#2#output-9'
-```
+会话内以 **`outputId`** 作为文件产物唯一键：
 
-- `messageUid`：所属 `AssistantMessage` 的 `uid`（回退 `String(id)`）
-- `index`：文件在所属消息 `property.artifacts` 数组中的下标
-- `outputId`：文件自身的 `AIFileInfo.outputId`
+- 同一 `outputId` 在多条 `AssistantMessage` 中出现时，`sessionArtifacts` 去重并保留**最后一次**出现的文件信息
+- `activeArtifactId`、列表 `:key`、`select` 事件参数均使用 `outputId`
+- 文件名可能重复，**不可**作为唯一键
 
 ## 完整触发链路
 
 ```
 ArtifactFileCard（点击）
-  └─ useArtifactPreviewConsumer().openPreview({ file, index, messageUid })
+  └─ useArtifactPreviewConsumer().openPreview({ file })
        └─ useArtifactPreviewProvider（ChatContainer）
-            ├─ activeArtifactId = buildArtifactId(...)
-            └─ onOpen(artifactId) → addCustomTab(FILE_ARTIFACT_TAB_NAME)
+            ├─ activeArtifactId = file.outputId
+            └─ onOpen(outputId) → addCustomTab(FILE_ARTIFACT_TAB_NAME) 展开并选中
                  └─ FileArtifactPanel（列表 + 下载头，@select → setActiveArtifactId）
                       └─ ArtifactPreviewHost（loader + 分类型 renderer）
+
+容器初始化
+  └─ ensureCustomTab(FILE_ARTIFACT_TAB_NAME) 常驻挂上（不展开侧栏）；因 order:-1 排在首位，
+     未主动切换过 Tab 时会成为默认选中面板；无产物时由面板展示整块空态
+
+sessionArtifacts 变化
+  └─ 仅维护命中态（无产物清空，命中项失效回落第一个）；不增删 Tab
 ```
 
 分类型预览策略见 [FileArtifactPanel 预览机制](../components/message/file-artifact-panel#预览机制)。
@@ -228,10 +224,11 @@ ArtifactFileCard（点击）
 - **职责单一**：composable 不直接调用 `useCustomTab`，侧栏 Tab 打开逻辑由 `onOpen` 注入；也不做正文 fetch / iframe 渲染
 - **ShallowRef 优先**：`activeArtifactId` 使用 `shallowRef`，避免不必要的深层响应式开销
 - **Consumer 兜底**：`useArtifactPreviewConsumer` 无 Provider 时返回 `undefined`，文件卡片在无容器上下文时自动不可点击
-- **与 useCustomTab 协作**：「文件产物」Tab 通过 `addCustomTab` 按需添加（`order: -1`、`closable: false`），会话无文件产物时由容器 `removeCustomTab` 清理
+- **与 useCustomTab 协作**：点击卡片走 `addCustomTab`（展开 + 选中）；容器初始化时走 `ensureCustomTab` 常驻挂载（不展开；因 `order: -1` 在未主动切换前会成为默认选中），无产物也不移除，由面板展示空态
 
 ## 关联组件
 
 - [ChatContainer](../components/setup/chat-container) — Provider 主场景，内置「文件产物」Tab
 - [FileArtifactPanel](../components/message/file-artifact-panel) — 侧栏列表与预览 Host 挂载
-- [AssistantMessage](../components/message/assistant-message) — 文件产物来源（`property.artifacts`）
+- [AssistantMessage](../components/message/assistant-message) — 文件产物来源（`property.artifacts`）
+- [useCustomTab](./use-custom-tab) — `addCustomTab` / `ensureCustomTab` 分工

package/dist/mcp/generated/docs/use-container-scroll.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。
+useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、jumpToBottom、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 toScrollBottom 缺省按距底部距离自动选择行为：超过 INSTANT_SCROLL_DISTANCE（600px）时瞬时贴底，否则平滑滚动，避免切换会话时出现长距离平滑滚动动画。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。
 
 ### 关联组件
 - **message-container** — Provider 挂载于消息列表滚动区域
@@ -35,7 +35,10 @@ useContainerScrollProvider(containerRef, bottomRef)
   ├── wheel 事件（passive）→ deltaY < 0 时 autoScrollEnabled=false
   │     （用户向上滚动时暂停自动滚动）
   │
-  ├── toScrollBottom() → autoScrollEnabled=true + bottomRef.scrollIntoView('smooth')
+  ├── jumpToBottom()   → autoScrollEnabled=true + container.scrollTop = scrollHeight（瞬时）
+  ├── toScrollBottom(behavior?) → autoScrollEnabled=true；
+  │     behavior 缺省时：距底部 > INSTANT_SCROLL_DISTANCE(600) → jumpToBottom()
+  │     否则 / 显式 'smooth' → bottomRef.scrollIntoView({ behavior:'smooth', block:'end' })
   ├── toScrollTop()    → containerRef.scrollTo({ top:0, behavior:'smooth' })
   │
   └── provide(CONTAINER_SCROLL_TOKEN, computed(() => ({
@@ -43,6 +46,7 @@ useContainerScrollProvider(containerRef, bottomRef)
             isScrollBottom,             // ShallowRef<boolean>（保持响应式）
             scrollBottomHeight,         // ShallowRef<number>（保持响应式）
             debouncedShowScrollBottomBtn, // customRef，防抖显示返回底部按钮
+            jumpToBottom,
             toScrollBottom,
             toScrollTop,
         })))