@blueking/chat-x 0.0.49-beta.2 → 0.0.49-beta.4

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

@@ -102,15 +102,15 @@ const doubled = computed(() => count.value * 2);
 
 ## 消息状态
 
-`status` 影响两处渲染：**内容区**和**工具调用状态标题**。
+`status` 直接影响 **内容区**（`ContentRender`）。`ToolCallRender` 的状态**按工具维度推导**（见下方「工具调用状态推导」），不直接等于本组件的 `status`。
 
-| `status`    | 内容区效果                          | ToolCallRender 标题 |
-| ----------- | ----------------------------------- | ------------------- |
-| `pending`   | 正常渲染（通常 content 为空）       | Loading + "调用中"  |
-| `streaming` | Markdown 自动补全未闭合语法         | Loading + "调用中"  |
-| `complete`  | 正常渲染完整 Markdown               | "调用成功" + 耗时   |
-| `error`     | 红色错误图标 + content 作为错误提示 | "调用失败"          |
-| `stop`      | 正常渲染（内容停留在中止时的状态）  | "调用成功"          |
+| `status`    | 内容区效果                          |
+| ----------- | ----------------------------------- |
+| `pending`   | 正常渲染（通常 content 为空）       |
+| `streaming` | Markdown 自动补全未闭合语法         |
+| `complete`  | 正常渲染完整 Markdown               |
+| `error`     | 红色错误图标 + content 作为错误提示 |
+| `stop`      | 正常渲染（内容停留在中止时的状态）  |
 
 ### Pending
 
@@ -130,7 +130,7 @@ const doubled = computed(() => count.value * 2);
 
 ## 工具调用
 
-当 AI 回复中包含工具调用时，传入 `toolCalls` 数组，每项自动渲染为 `ToolCallRender`，位于内容区下方。`status` 会同步传递给每个 `ToolCallRender` 以反映调用状态。
+当 AI 回复中包含工具调用时，传入 `toolCalls` 数组，每项自动渲染为 `ToolCallRender`，位于内容区下方。传给每个 `ToolCallRender` 的 `status` 按下方优先级从 `toolCall.toolMessage` 推导，而非直接同步本组件的 `status`。
 
 ### 单个工具调用
 
@@ -278,13 +278,17 @@ AI 可在一次回复中发起多个工具调用，组件依次渲染：
 
 **渲染效果**
 
-### 工具调用状态随消息状态变化
+### 工具调用状态推导
 
-`ToolCallRender` 的状态标题直接来自 `AssistantMessage` 的 `status` prop：
+传给每个 `ToolCallRender` 的 `status` 按以下优先级计算：
 
-**调用中**（`status = "streaming"`）：
+1. 无 `toolMessage` → `MessageStatus.Pending`（调用中）
+2. `toolMessage.error` 为真 → `MessageStatus.Error`（调用失败）
+3. 否则 → `toolMessage.status ??` 本组件 `status`
 
-**调用成功**（`status = "complete"` + `toolMessage`）：
+**调用中**（有 `toolCalls`、尚无 `toolMessage`；即便助手 `status` 已是 `complete` 也显示调用中）：
+
+**调用成功**（`toolMessage.status = "complete"`）：
 
 ## 自定义内容渲染
 
@@ -381,7 +385,7 @@ AI 可在一次回复中发起多个工具调用，组件依次渲染：
 | `html` / `markdown` / `md` / `txt` / `json` | `download_url` | 正文直渲染（srcdoc / MarkdownContent / `<pre>`） |
 | `pdf` / `jpg` 等 | `preview_url` | iframe（一般为后台转好的 PDF） |
 
-`md` 与 `markdown` 等价（见 `AIFileType.Md` / `AIFileType.Markdown`）。预览重载、`force` 重试与取链约定见 [FileArtifactPanel 预览机制](/components/message/file-artifact-panel#预览机制)。
+`md` 与 `markdown` 等价（见 `AIFileType.Md` / `AIFileType.Markdown`）。预览重载、重试与取链约定见 [FileArtifactPanel 预览机制](/components/message/file-artifact-panel#预览机制)。
 
 ```vue
 <template>
@@ -424,7 +428,7 @@ AI 可在一次回复中发起多个工具调用，组件依次渲染：
 | 属性名    | 类型                    | 说明                                                                                      |
 | --------- | ----------------------- | ----------------------------------------------------------------------------------------- |
 | content   | `string`                | AI 回复文本，支持 Markdown；空值时不渲染内容区                                            |
-| status    | `MessageStatus`         | 影响 ContentRender / ToolCallRender 状态表现                                              |
+| status    | `MessageStatus`         | 影响 ContentRender；ToolCallRender 在无 toolMessage.status 时回退使用此值                 |
 | toolCalls | `ToolCall[]`            | 工具调用列表，每项渲染一个 `ToolCallRender`                                               |
 | id        | `number \| string`      | 消息 ID；无 `uid` 时回退为 `messageUid`                                                   |
 | messageId | `number \| string`      | 消息唯一标识                                                                              |

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

@@ -247,8 +247,8 @@ ai-chat-container（:data-ai-size="size"）
 - **主动打开**：点击 AI 回复中的文件卡片（[ArtifactFileCard](/components/message/assistant-message)）时，容器通过 `useArtifactPreviewProvider` 以 `outputId` 命中该文件，再 `addCustomTab` 展开侧栏并选中「文件产物」
 - **排序 / 关闭**：`order: -1` 排在「执行情况」之前，`closable: false` 不可关闭
 - **显隐解耦**：该 Tab 存在时，侧栏展示不再受「`executionGroups` 为空」约束（即使当前会话没有执行类消息，也能独立展示文件产物侧栏）；会话切换或无文件产物时自动移除并重置命中态
-- **内容**：由 [FileArtifactPanel](/components/message/file-artifact-panel) 渲染列表与下载头，预览委托内部 `ArtifactPreviewHost`；`download_url` / `preview_url` 通过 `onArtifactClick` 异步获取。文本类（`html` / `markdown` / `md` / `txt` / `json`）拉 `download_url` 正文直渲染（`md` 与 `markdown` 等价）；其余类型用 `preview_url` iframe（一般为后台转好的 PDF）。预览重载键为 `outputId:type`；失败重试会 `force` 绕过 URL 缓存
-- **状态管理**：命中、切换与 URL 缓存由 [useArtifactPreview](/composables/use-artifact-preview) 提供（Provider 在容器内、Consumer 在文件卡片 / 面板内）；正文加载与分类型渲染由 Host 内部完成；常规取链只传 `file`，勿传 `undefined` 作为第二参
+- **内容**：由 [FileArtifactPanel](/components/message/file-artifact-panel) 渲染列表与下载头，预览委托内部 `ArtifactPreviewHost`；`download_url` / `preview_url` 通过 `onArtifactClick` 异步获取（每次重新取链，无 URL 缓存）。文本类（`html` / `markdown` / `md` / `txt` / `json`）拉 `download_url` 正文直渲染（`md` 与 `markdown` 等价）；其余类型用 `preview_url` iframe（一般为后台转好的 PDF）。预览重载键为 `outputId:type`；失败重试再次 `load()` 重新取链
+- **状态管理**：命中与切换由 [useArtifactPreview](/composables/use-artifact-preview) 提供（Provider 在容器内、Consumer 在文件卡片 / 面板内）；正文加载与分类型渲染由 Host 内部完成；取链只传 `file`，同文件并发去重
 - **未传 `onArtifactClick`**：下载按钮隐藏，预览区展示无数据
 
 详见 [FileArtifactPanel 文件产物预览](/components/message/file-artifact-panel) 与 [useArtifactPreview 文件产物预览](/composables/use-artifact-preview)。
@@ -710,7 +710,7 @@ ChatContainer 的 Props 继承自 `ChatInputProps` 和 `MessageContainerProps`
 | size                      | `'normal' \| 'small'`                                                                    | `'small'` | 字号主题：`small` 12px / `normal` 14px；根节点设置 `data-ai-size` 并注入 `useGlobalConfig`                                           |
 | welcomeTitle              | `string`                                                                                 | —         | 欢迎页标题；未传时默认展示「你好，我是小鲸」                                                                                         |
 | onCustomTabChange         | `(tab: CustomTab) => Promise<any>`                                                       | —         | 自定义 Tab 切换回调，返回值作为 Tab 组件 props                                                                                       |
-| onArtifactClick           | `(file: AIFileInfo) => Promise<{ download_url?: string; preview_url?: string }>`          | —         | 异步获取下载 / 预览链接（按 `outputId` 缓存）。文本类预览依赖 `download_url`，iframe 类依赖 `preview_url`；未传则隐藏下载、预览无数据 |
+| onArtifactClick           | `(file: AIFileInfo) => Promise<{ download_url?: string; preview_url?: string }>`          | —         | 异步获取下载 / 预览链接（每次调用重新获取，无缓存；同文件并发去重）。文本类预览依赖 `download_url`，iframe 类依赖 `preview_url`；未传则隐藏下载、预览无数据 |
 
 > 其余 Props（如 `messages`、`messageStatus`、`onSendMessage`、`shortcuts` 等）继承自 [ChatInput](/components/input/chat-input) 与 [MessageContainer](/components/setup/message-container)。
 

package/dist/mcp/generated/docs/file-artifact-panel.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-汇总当前会话所有 AssistantMessage 的 artifacts（按 outputId 去重），支持关键词搜索、列表选中与下载； 预览区委托 ArtifactPreviewHost：按类型走 text_from_download（html / markdown / md / txt / json） 或 preview_url_iframe（其余类型）；download_url / preview_url 经 onArtifactClick 异步获取（TTL 缓存，重试 force）； 预览重载键为 outputId:type；常规 resolveArtifactUrls 只传 file。 源码位置：src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue。
+汇总当前会话所有 AssistantMessage 的 artifacts（按 outputId 去重），支持关键词搜索、列表选中与下载； 预览区委托 ArtifactPreviewHost：按类型走 text_from_download（html / markdown / md / txt / json） 或 preview_url_iframe（其余类型）；download_url / preview_url 经 onArtifactClick 每次异步获取（无 URL 缓存，并发去重）； 预览重载键为 outputId:type；重试再次调用 load() 重新取链。 源码位置：src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue。
 
 ### 关联组件
 - **assistant-message** — 文件产物来源于 AssistantMessage.property.artifacts
@@ -31,7 +31,7 @@
 - **会话级聚合**：拍平当前会话所有 `AssistantMessage.property.artifacts`，以 `outputId` 去重后统一在一个列表内展示
 - **唯一命中**：以 `outputId` 作为会话内唯一键（同 `outputId` 视为同一文件）；文件名可能重复，不可作唯一键
 - **关键词搜索**：按文件名实时过滤列表
-- **异步取链**：`AIFileInfo` 本身不含 `url` / `previewUrl`，通过 `ChatContainer` 的 `onArtifactClick` 按 `outputId` 获取 `download_url` / `preview_url`（TTL 8 分钟缓存；预览重试会 `force` 刷新）
+- **异步取链**：`AIFileInfo` 本身不含 `url` / `previewUrl`，通过 `ChatContainer` 的 `onArtifactClick` 按 `outputId` 获取 `download_url` / `preview_url`（每次重新取链，无 URL 缓存；同文件并发去重）
 - **职责拆分**：
   - **面板本身**：列表、搜索、预览头（文件名 / 图标 / 下载）
   - **`ArtifactPreviewHost`**：按策略加载正文或预览 URL，分派到对应 renderer；展示 loading / empty / error（含重试）
@@ -206,8 +206,8 @@ sessionArtifacts 有产物时
 ### 重载与取链约定
 
 - **重载键**：`ArtifactPreviewHost` 以 `` `${outputId}:${type}` `` 监听文件变化；`outputId` 或 `type` 任一变化会重新 `load()`，仅改文件名等其它字段不会
-- **常规取链**：`resolveArtifactUrls(file)`，只传文件，不传第二参
-- **重试 / 强刷**：错误态点击重试走 `load({ force: true })` → `resolveArtifactUrls(file, { force: true })`，绕过 TTL 缓存重新取链
+- **取链**：`resolveArtifactUrls(file)` 每次重新调用 `onArtifactClick`；同文件进行中的请求会复用（并发去重）
+- **重试**：错误态点击重试再次走 `load()`，重新取链并加载
 - **竞态**：切换文件时 `useArtifactPreviewLoader` 用 `loadSeq` + `AbortController` 中断上一次 `fetch`，避免过期结果覆盖最新内容
 
 下载图标仍由面板用 bkui `Loading` spin 单独表达。

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 回复联动选中
 
 ## 基础用法
@@ -533,10 +533,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

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` / `completed` / `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` 将 `Completed`（`completed`）与 `Complete` / `Success` 一并视为成功；主题 `$toolcallStatusMap` 同步提供 `completed` 色值。`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（值为 outputId），openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（TTL 8 分钟缓存；常规只传 file，force 可强制刷新，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 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
@@ -19,7 +19,7 @@ Provider/Consumer 模式的文件产物预览状态管理。Provider 在 `ChatCo
 
 **职责边界**：
 
-- **本 composable**：维护「命中文件」与「URL 解析」（TTL 缓存 + 并发去重；常规 `resolveArtifactUrls(file)`，重试可 `force` 刷新）；打开侧栏 Tab（`addCustomTab`）由容器通过 `onOpen` 注入
+- **本 composable**：维护「命中文件」与「URL 解析」（每次重新取链 + 并发去重）；打开侧栏 Tab（`addCustomTab`）由容器通过 `onOpen` 注入
 - **不在本 composable**：聚合会话文件列表、渲染预览面板、按类型 fetch 正文 / iframe 展示 —— 分别由 `useMessageGroup.sessionArtifacts`、`FileArtifactPanel`、内部 `ArtifactPreviewHost` + `useArtifactPreviewLoader` 承担（预览重载键为 `outputId:type`）
 
 ## 函数签名
@@ -36,7 +36,7 @@ function useArtifactPreviewProvider(options: {
   activeArtifactId: ShallowRef<string>;
   canResolveArtifactUrl: ComputedRef<boolean>;
   openPreview: (payload: OpenArtifactPreviewPayload) => void;
-  resolveArtifactUrls: (file: AIFileInfo, options?: { force?: boolean }) => Promise<ArtifactUrlResult>;
+  resolveArtifactUrls: (file: AIFileInfo) => Promise<ArtifactUrlResult>;
   setActiveArtifactId: (id: string) => void;
 };
 ```
@@ -50,7 +50,7 @@ function useArtifactPreviewConsumer():
       activeArtifactId: Ref<string>;
       canResolveArtifactUrl: ComputedRef<boolean>;
       openPreview: (payload: OpenArtifactPreviewPayload) => void;
-      resolveArtifactUrls: (file: AIFileInfo, options?: { force?: boolean }) => Promise<ArtifactUrlResult>;
+      resolveArtifactUrls: (file: AIFileInfo) => Promise<ArtifactUrlResult>;
       setActiveArtifactId: (id: string) => void;
     };
 ```
@@ -166,7 +166,7 @@ const onArtifactClick = async (file: AIFileInfo) => {
 | activeArtifactId    | `ShallowRef<string>`                      | 当前命中的文件 `outputId`                                            |
 | canResolveArtifactUrl | `ComputedRef<boolean>`                  | 是否具备异步取链能力（有 `onArtifactClick` 时为 true，下载按钮据此显隐） |
 | openPreview         | `(payload: OpenArtifactPreviewPayload) => void` | 由文件卡片触发：以 `file.outputId` 更新命中态、调用 `onOpen`   |
-| resolveArtifactUrls | `(file: AIFileInfo, options?: { force?: boolean }) => Promise<ArtifactUrlResult>` | 调用 `onArtifactClick` 取链；成功结果按 `outputId` 缓存 8 分钟；**常规调用只传 `file`**，仅预览重试 / 强刷传 `{ force: true }`（不要传 `undefined` 作为第二参）；并发去重 |
+| resolveArtifactUrls | `(file: AIFileInfo) => Promise<ArtifactUrlResult>` | 调用 `onArtifactClick` 取链；每次重新获取，不缓存；同文件并发去重 |
 | setActiveArtifactId | `(id: string) => void`                    | 直接设置命中文件 `outputId`；侧栏列表内切换选中时使用                |
 
 ## 类型定义

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,
         })))

package/dist/mcp/generated/docs/use-message-group.md

@@ -71,15 +71,18 @@ role=user  role=tool     其他 role
 `role: 'tool'` 消息不会独立渲染，而是通过 `toolCallId` 注入到对应 AssistantMessage 的 `toolCall.toolMessage` 字段：
 
 ```typescript
-const toolMessage = messages.find(
+const assistantToolMessage = messages.find(
   m => m.role === 'assistant' && m.toolCalls?.some(t => t.id === message.toolCallId),
-);
-if (toolMessage) {
-  const toolCall = toolMessage.toolCalls?.find(t => t.id === message.toolCallId);
+) as AssistantMessage | undefined;
+if (assistantToolMessage) {
+  const toolCall = assistantToolMessage.toolCalls?.find(t => t.id === message.toolCallId);
   if (toolCall) {
     toolCall.toolMessage = message;
   }
-  // 同步 assistant 状态（错误等）
+  // error 时强制 assistant 为 Error；否则保留原 status，空值兜底 Complete
+  assistantToolMessage.status = message.error
+    ? MessageStatus.Error
+    : assistantToolMessage.status || MessageStatus.Complete;
 }
 ```
 

package/dist/mcp/generated/index.json

@@ -1,6 +1,6 @@
 {
   "version": "2.0.0",
-  "generatedAt": "2026-08-06T04:13:41.238Z",
+  "generatedAt": "2026-08-07T07:34:43.673Z",
   "domains": {
     "setup": {
       "label": "对话搭建",
@@ -1115,7 +1115,7 @@
       "slug": "file-artifact-panel",
       "kind": "component",
       "description": "汇总当前会话全部文件产物，支持搜索、选中与分类型预览，挂载在 ChatContainer 侧栏「文件产物」Tab。",
-      "aiSummary": "汇总当前会话所有 AssistantMessage 的 artifacts（按 outputId 去重），支持关键词搜索、列表选中与下载； 预览区委托 ArtifactPreviewHost：按类型走 text_from_download（html / markdown / md / txt / json） 或 preview_url_iframe（其余类型）；download_url / preview_url 经 onArtifactClick 异步获取（TTL 缓存，重试 force）； 预览重载键为 outputId:type；常规 resolveArtifactUrls 只传 file。 源码位置：src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue。",
+      "aiSummary": "汇总当前会话所有 AssistantMessage 的 artifacts（按 outputId 去重），支持关键词搜索、列表选中与下载； 预览区委托 ArtifactPreviewHost：按类型走 text_from_download（html / markdown / md / txt / json） 或 preview_url_iframe（其余类型）；download_url / preview_url 经 onArtifactClick 每次异步获取（无 URL 缓存，并发去重）； 预览重载键为 outputId:type；重试再次调用 load() 重新取链。 源码位置：src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue。",
       "relatedComponents": [
         {
           "slug": "assistant-message",
@@ -1586,7 +1586,7 @@
       "slug": "use-artifact-preview",
       "kind": "composable",
       "description": "Provider/Consumer 模式的文件产物预览状态管理，用于 ChatContainer 侧栏「文件产物」Tab 的命中与切换。 Provider 在 ChatContainer 中创建，Consumer 在深层文件卡片中注入使用。",
-      "aiSummary": "useArtifactPreviewProvider 维护 activeArtifactId（值为 outputId），openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（TTL 8 分钟缓存；常规只传 file，force 可强制刷新，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。",
+      "aiSummary": "useArtifactPreviewProvider 维护 activeArtifactId（值为 outputId），openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（每次重新取链，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。",
       "relatedComponents": [
         {
           "slug": "chat-container",
@@ -1644,7 +1644,7 @@
       "slug": "use-container-scroll",
       "kind": "composable",
       "description": "为消息容器提供滚动控制的组合式函数对，通过 **Provider/Consumer** 模式在父子组件间共享滚动状态。",
-      "aiSummary": "useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。",
+      "aiSummary": "useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、jumpToBottom、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 toScrollBottom 缺省按距底部距离自动选择行为：超过 INSTANT_SCROLL_DISTANCE（600px）时瞬时贴底，否则平滑滚动，避免切换会话时出现长距离平滑滚动动画。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。",
       "relatedComponents": [
         {
           "slug": "message-container",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/chat-x",
-  "version": "0.0.49-beta.2",
+  "version": "0.0.49-beta.4",
   "description": "蓝鲸智云 AI Chat 组件库 —— 遵循 AG-UI，为 AI Agent 和人类开发者共同设计的对话 UI 组件库。",
   "main": "index.js",
   "bin": {
@@ -79,7 +79,7 @@
     "vitepress": "2.0.0-alpha.16",
     "vitest": "^4.0.18",
     "vue-tsc": "^3.1.4",
-    "@blueking/chat-helper": "0.0.12-beta.14"
+    "@blueking/chat-helper": "0.0.12-beta.15"
   },
   "scripts": {
     "dev": "vite --config vite.config.ts",