@blueking/chat-x 0.0.47-beta.4 → 0.0.49-beta.1

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

@@ -1,11 +1,12 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-完整对话容器，组合消息列表、输入区、快捷指令、执行摘要、分享选择和自定义 Tab。 源码位置：src/components/chat-container/chat-container.vue。
+完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。 透传 models / selectedModel；支持 welcomeTitle 与 #welcome。 源码位置：src/components/chat-container/chat-container.vue。
 
 ### 关联组件
 - **message-container** — 消息列表与滚动区域
 - **chat-input** — 对话输入与快捷指令入口
+- **model-selector** — 透传 models / selectedModel，在输入区展示模型选择器
 - **shortcut-render** — 快捷指令表单浮层
 - **execution-summary** — 执行摘要侧栏与定位
 - **selection-footer** — 多选分享底部操作栏
@@ -14,30 +15,23 @@
 <!-- FULL DOC -->
 
 # ChatContainer 聊天容器
-## 源码事实
 
-- **源码位置**：`src/components/chat-container/chat-container.vue`
-- **能力域**：对话搭建
-- **能力说明**：完整对话容器，组合消息列表、输入区、快捷指令、执行摘要、分享选择和自定义 Tab。
+> **能力域**：对话搭建 ｜ **源码**：`src/components/chat-container/chat-container.vue`
 
-> **能力域**：对话搭建
-
-顶层聊天容器组件，整合了 `MessageContainer`（消息列表）、`ChatInput`（输入框）、`ExecutionSummary`（执行摘要面板）、`ShortcutRender`（快捷指令表单）和 `SelectionFooter`（多选操作栏）。提供完整的 AI 对话界面布局能力。
+顶层聊天容器，整合 `MessageContainer`（消息列表）、`ChatInput`（输入框）、`ExecutionSummary`（执行摘要）、`ShortcutRender`（快捷指令表单）和 `SelectionFooter`（多选操作栏），提供完整 AI 对话界面布局。
 
 ## 核心能力
 
-- **分栏布局**：基于 `ResizeLayout` 的可拖拽分栏；**侧栏是否展示 Tab / 执行摘要、以及分栏是否进入折叠样式（`ai-is-collapse`）以 `executionGroups` 与执行情况搜索关键词 `keyword` 共同决定**（`executionGroups` 由 `useMessageGroup` 从消息中过滤工具调用与 FlowAgent 记录；`keyword` 来自 `ExecutionSummary` 的 `@update-keyword`）。当 `executionGroups` 为空且未输入搜索词时，侧栏 Tab 与执行摘要不展示；**用户正在搜索执行情况时（`keyword` 非空），即使暂无执行类消息也会保留侧栏**，避免搜索态被折叠
-- **消息分组**：内置 `useMessageGroup` 自动处理消息分组、Tool 合并、Loading 注入
-- **输入区状态推导**：传给 `MessageContainer` 与 `ChatInput` 的 `messageStatus` 为内部计算值 `inputStatus`：当分组中存在 id 为 `LOADING_MESSAGE_ID`（`'__loading__'`，由 `useMessageGroup` 注入的占位 Loading 消息）时，对内使用 `MessageStatus.Fetching`；否则使用外部传入的 `messageStatus`。用于在「已发用户消息、尚未流式」阶段与流式中一致地展示停止能力，并避免输入区重复发送
-- **待审批发送阻塞**：当消息中存在 `AIDevToolApproval` 且状态为 `pending` / `draft` 的中断项时，`useMessageGroup` 会返回待审批提示，容器在输入区上方展示提示并通过 `ChatInput.sendDisabledTip` 禁止继续发送
-- **用户问题中断**：当消息中存在待回答 `UserQuestion` 中断时，容器会在输入区上方挂载 `UserQuestionCard`；结构化作答走 `onInterruptResume`，用户在输入框直接发送时走 `onSendMessage` 并在第三参数附带 skip 用的 `payload`（`status: 'cancelled'`）与 `interrupt`，且不会自动清空输入框
-- **执行摘要**：侧边栏展示工具调用 / FlowAgent 执行记录，支持关键词搜索和对话定位
-- **侧栏全屏**：Tab 栏右侧提供全屏/退出全屏按钮，基于 `useFullScreen` 将侧栏区域（`.ai-full-screen-wrapper`）以浏览器原生全屏展示；全屏时 Tippy 的 `appendTo` 自动切换为全屏容器，避免 tooltip 被遮挡
-- **自定义 Tab**：通过 `useCustomTabProvider` 支持动态添加自定义 Tab（如节点详情）
-- **分享模式**：内置消息多选分享流程，选中用户消息后确认分享
-- **渲染模式注入**：`renderMode` 会通过内部 Provider 下传给后代内容组件；`Share` 分享态开放流程智能体只读查看（侧栏 Tab / 执行情况 / 节点「详情」「有效证据」/ 耗时均保留），仅隐藏底部输入区与「重试 / 跳过」等交互操作
-- **字号主题**：通过 `size` 控制 `small`（默认 12px）/ `normal`（14px）两档字号；根节点设置 `data-ai-size`，子组件通过 CSS 变量（`--ai-font-size` 等）响应式缩放；浮层（Tippy / Teleport）会同步 `document.body.dataset.aiSize`，卸载时自动清理
-- **空状态欢迎页**：无消息时展示欢迎语和开场白
+- **分栏布局**：基于 `ResizeLayout`；侧栏 Tab / 执行摘要是否展示，以及是否进入 `ai-is-collapse`，由 `executionGroups` 与搜索词 `keyword` 共同决定。无执行数据且未搜索时隐藏侧栏；搜索中（`keyword` 非空）即使暂无执行消息也保留侧栏
+- **消息分组**：内置 `useMessageGroup`，自动分组、Tool 合并、Loading 注入
+- **输入区状态推导**：对内 `messageStatus` 取 `inputStatus`——分组中存在 `LOADING_MESSAGE_ID`（`'__loading__'`）时用 `MessageStatus.Fetching`，否则用外部 `messageStatus`，保证「已发未流式」阶段也能停止、并避免重复发送
+- **待审批发送阻塞**：存在 `AIDevToolApproval` 且为 `pending` / `draft` 时，输入区上方提示，并通过 `ChatInput.sendDisabledTip` 禁止发送
+- **用户问题中断**：待回答 `UserQuestion` 时挂载 `UserQuestionCard`；结构化作答走 `onInterruptResume`，输入框直接发送走 `onSendMessage`（第三参数带 skip `payload` 与 `interrupt`），且不自动清空输入框
+- **执行摘要 / 侧栏全屏 / 自定义 Tab**：侧栏展示工具调用与 FlowAgent 记录，支持搜索定位；Tab 栏可全屏；`useCustomTabProvider` 支持动态 Tab
+- **模型选择**：透传 `models`、`v-model:selectedModel` 与 `@modelChange` 至 `ChatInput`，传入 `models` 后在发送按钮左侧展示 [ModelSelector](/components/input/model-selector)
+- **分享模式 / 渲染模式**：内置多选分享；`renderMode` 经 Provider 下传。`Share` 态开放侧栏只读查看，隐藏底部输入与「重试 / 跳过」等交互
+- **字号主题**：`size` 为 `small`（默认 12px）/ `normal`（14px）；根节点 `data-ai-size`，浮层同步 `document.body.dataset.aiSize`
+- **空状态欢迎页**：无消息时展示 Banner、`welcomeTitle`（默认「你好，我是小鲸」）与 `openingRemark`
 
 ## 组件结构
 
@@ -49,21 +43,18 @@ ai-chat-container（:data-ai-size="size"）
     │   ├── .ai-full-screen-wrapper（全屏目标容器，ref=fullScreenRef）
     │   │   ├── Tab 标签页
     │   │   │   ├── 执行情况（默认 Tab）
-    │   │   │   ├── 自定义 Tab × N（可关闭；标签可由 `getSideTabRenderComponent` 自定义）
-    │   │   │   └── #setting 插槽 → 全屏/退出全屏 ToolBtn（FullScreenIcon / UnFullScreenIcon）
+    │   │   │   ├── 自定义 Tab × N（可关闭；标签可由 getSideTabRenderComponent 自定义）
+    │   │   │   └── #setting → 全屏/退出全屏 ToolBtn
     │   │   ├── ExecutionSummary（执行情况 Tab 内容）
-    │   │   └── 自定义 Tab 组件（`getSideRenderComponent` 优先，否则 `data.component`；可向子组件注入 #locateButton）
-    │   └── collapse-button（折叠按钮，CollapsedIcon；折叠时图标旋转，hover 高亮 #3a84ff）
+    │   │   └── 自定义 Tab 组件（getSideRenderComponent 优先，否则 data.component；可注入 #locateButton）
+    │   └── collapse-button（CollapsedIcon）
     └── main（主内容区）
-        ├── MessageContainer（有消息时）
-        │   ├── #group 插槽（可选，自定义消息组内容）
-        │   ├── #message 插槽（可选，自定义单条消息）
-        │   └── 消息列表 + 工具栏
-        ├── 欢迎页（无消息时，容器 .ai-welcome-content）
-        │   └── welcome 插槽（默认：Banner + 欢迎标题 + 开场白 ContentRender；自定义则整块替换）
-        ├── SelectionFooter（分享模式时）
+        ├── MessageContainer（有消息时；#group / #message 可自定义）
+        ├── 欢迎页（无消息时 .ai-welcome-content）
+        │   └── #welcome（默认：Banner + welcomeTitle + openingRemark；自定义则整块替换）
+        ├── SelectionFooter（分享模式）
         ├── ShortcutRender（有快捷指令时）
-        └── ChatInput（默认状态，待审批时通过 interrupt slot 展示 InputInfoAlert）
+        └── ChatInput（透传 models / selectedModel；interrupt 槽展示 UserQuestionCard / InputInfoAlert）
 ```
 
 ## 基础用法
@@ -142,9 +133,9 @@ ai-chat-container（:data-ai-size="size"）
 
 侧边栏默认包含「执行情况」Tab，展示所有工具调用和 FlowAgent 类型的 Activity 消息。支持关键词搜索过滤和点击定位到对话中的消息位置。
 
-**展示条件**：当 `executionGroups` 为空且 `keyword` 为空时，不渲染侧栏 Tab 与 `ExecutionSummary`（折叠按钮亦隐藏）；主区域仍可正常展示 `messages` 中的对话内容。用户在执行情况中输入搜索词后，侧栏会保持展示以显示「搜索结果为空」等状态。`renderMode === Share` 分享态同样按上述执行数据条件展示侧栏（开放只读查看流程智能体详情/证据/执行情况），不再强制隐藏折叠；仅底部输入区保持隐藏。
+**展示条件**：当 `executionGroups` 为空且 `keyword` 为空时，不渲染侧栏 Tab 与 `ExecutionSummary`（折叠按钮亦隐藏）；主区域仍可正常展示 `messages` 中的对话内容。用户在执行情况中输入搜索词后，侧栏会保持展示以显示「搜索结果为空」等状态。`renderMode === Share` 分享态同样按上述执行数据条件展示侧栏（开放只读查看流程智能体详情/证据/执行情况），不再强制隐藏折叠；仅底部输入区保持隐藏。**例外**：当[「文件产物」Tab](#内置-文件产物-tab)存在时，侧栏不再受「`executionGroups` 为空」约束，可独立展示文件预览。
 
-**自定义 Tab 联动**：当 `executionGroups` 变为空且搜索词已清空时，容器会**自动重置自定义 Tab**（`resetCustomTab`），避免残留节点详情等 Tab；若用户仍在搜索（`keyword` 非空），不会触发重置。
+**自定义 Tab 联动**：当 `executionGroups` 变为空且搜索词已清空时，容器会**自动重置自定义 Tab**（`resetCustomTab`），避免残留节点详情等 Tab；若用户仍在搜索（`keyword` 非空）或存在「文件产物」Tab，不会触发重置。
 
 ```vue
 <template>
@@ -248,6 +239,83 @@ ai-chat-container（:data-ai-size="size"）
 </script>
 ```
 
+### 内置「文件产物」Tab
+
+除「执行情况」外，容器内置一个按需出现的固定 Tab —— **「文件产物」**（`name: 'file-artifact'`），用于聚合预览当前会话所有 `AssistantMessage.property.artifacts`：
+
+- **触发**：点击 AI 回复中的文件卡片（[ArtifactFileCard](/components/message/assistant-message)）时，容器通过 `useArtifactPreviewProvider` 命中该文件并 `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）
+- **状态管理**：命中、切换与 URL 缓存由 [useArtifactPreview](/composables/use-artifact-preview) 提供（Provider 在容器内、Consumer 在文件卡片 / 面板内）；正文加载与分类型渲染由 Host 内部完成
+- **未传 `onArtifactClick`**：下载按钮隐藏，预览区展示无数据
+
+详见 [FileArtifactPanel 文件产物预览](/components/message/file-artifact-panel) 与 [useArtifactPreview 文件产物预览](/composables/use-artifact-preview)。
+
+#### 接入示例
+
+```vue
+<template>
+  <ChatContainer
+    v-model="input"
+    :messages="messages"
+    :on-artifact-click="onArtifactClick"
+    @send-message="handleSend"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref, shallowRef } from 'vue'
+  import {
+    ChatContainer,
+    MessageRole,
+    MessageStatus,
+    type AIFileInfo,
+    type Message,
+  } from '@blueking/chat-x'
+
+  const input = ref('')
+  const messages = shallowRef<Message[]>([
+    {
+      id: 'u1',
+      messageId: 'u1',
+      role: MessageRole.User,
+      status: MessageStatus.Complete,
+      content: '整理本周评审材料',
+    },
+    {
+      id: 'a1',
+      messageId: 'a1',
+      uid: 'assistant-uid-1',
+      role: MessageRole.Assistant,
+      status: MessageStatus.Complete,
+      content: '已生成评审材料，点击卡片可在侧栏预览：',
+      property: {
+        artifacts: [
+          { name: '周报.html', outputId: 'a-html', size: 10240, type: 'html' },
+          { name: '说明.md', outputId: 'a-md', size: 8192, type: 'md' },
+          { name: '配置.json', outputId: 'a-json', size: 2048, type: 'json' },
+          { name: '立项.pdf', outputId: 'a-pdf', size: 204800, type: 'pdf' },
+        ] satisfies AIFileInfo[],
+      },
+    },
+  ])
+
+  /** 文本类预览依赖 download_url；iframe 类依赖 preview_url */
+  const onArtifactClick = async (file: AIFileInfo) => {
+    const res = await api.getArtifactUrls(file.outputId)
+    return {
+      download_url: res.download_url,
+      preview_url: res.preview_url,
+    }
+  }
+
+  const handleSend = () => {
+    /* ... */
+  }
+</script>
+```
+
 ### 自定义 Tab 与「在对话中定位」
 
 `addCustomTab` 的 `data` 可携带 **`messageUid`**（与对应活动消息的 `message.uid` 一致）。`ChatContainer` 在侧栏用 `<component :is="sideRenderComponent">`（内部计算属性，见上文「侧栏渲染扩展」）渲染自定义 Tab 时，会向子组件提供 **`locateButton` 插槽**：默认渲染「在对话中定位」按钮，点击后调用内部 `handleLocateMessageGroup(messageUid)`，优先滚动到主区域 `document.getElementById(messageUid)`；若不存在该节点，则在当前 `messageGroups` 中查找包含 `message.uid === messageUid` 的消息组，并滚动到该组的容器（`MessageGroup.uid` 作为组级 `id`）。
@@ -296,7 +364,7 @@ ai-chat-container（:data-ai-size="size"）
 
 ## 开场白
 
-无消息时展示欢迎页，通过 `openingRemark` 设置开场白内容（支持 Markdown）：
+无消息时展示欢迎页：`welcomeTitle` 控制标题（未传时默认「你好，我是小鲸」），`openingRemark` 为开场白（支持 Markdown）：
 
 ```vue
 <template>
@@ -304,6 +372,7 @@ ai-chat-container（:data-ai-size="size"）
     v-model="inputValue"
     :messages="[]"
     :message-status="messageStatus"
+    welcome-title="你好，我是小鲸"
     opening-remark="你好！我是 AI 小鲸 🐳，可以帮你：\n\n- 编写和优化代码\n- 解答技术问题\n- 分析和调试错误"
     :on-send-message="handleSendMessage"
   />
@@ -312,7 +381,7 @@ ai-chat-container（:data-ai-size="size"）
 
 ### 自定义欢迎内容
 
-通过 `welcome` 插槽可完全自定义欢迎页内容，插槽参数 `openingRemark` 为传入的开场白文本：
+通过 `#welcome` 可整块替换默认欢迎区，插槽参数为 `{ openingRemark, welcomeTitle }`：
 
 ```vue
 <template>
@@ -320,12 +389,14 @@ ai-chat-container（:data-ai-size="size"）
     v-model="inputValue"
     :messages="[]"
     :message-status="messageStatus"
-    opening-remark="欢迎使用 AI 助手"
+    welcome-title="欢迎使用 AI 助手"
+    opening-remark="选择一个快捷入口开始对话"
     :on-send-message="handleSendMessage"
   >
-    <template #welcome="{ openingRemark }">
+    <template #welcome="{ openingRemark, welcomeTitle }">
       <div class="my-welcome">
-        <h3>{{ openingRemark }}</h3>
+        <h3>{{ welcomeTitle }}</h3>
+        <p>{{ openingRemark }}</p>
         <div class="quick-actions">
           <button @click="handleQuickAction('code')">写代码</button>
           <button @click="handleQuickAction('debug')">调试</button>
@@ -337,7 +408,7 @@ ai-chat-container（:data-ai-size="size"）
 </template>
 ```
 
-> **注意**：使用 `welcome` 插槽后，将**整块替换**默认欢迎区（含 Banner 图标、默认欢迎标题与 `openingRemark` 的 `ContentRender` 渲染），需自行编排完整欢迎页；插槽参数 `openingRemark` 仍可用于读取传入的开场白文本。
+> **注意**：使用 `#welcome` 后将**整块替换**默认欢迎区（Banner、标题与开场白的 `ContentRender`），需自行编排完整欢迎页。
 
 **渲染效果**
 
@@ -486,22 +557,103 @@ ai-chat-container（:data-ai-size="size"）
 </template>
 
 <script setup lang="ts">
-  import { type Message } from '@blueking/chat-x';
+  import { type IToolBtn, type Message } from '@blueking/chat-x';
 
-  const handleConfirmShare = (selectedMessages: Message[]) => {
+  // 第二参数 source 为触发多选态的按钮对象，可据此区分 share / save 等不同确认场景
+  const handleConfirmShare = (selectedMessages: Message[], source?: IToolBtn) => {
+    if (source?.id === 'save') {
+      console.log('保存选中的消息:', selectedMessages);
+      return;
+    }
     console.log('分享消息:', selectedMessages);
   };
 </script>
 ```
 
+### 自定义按钮触发多选（triggerSelection）
+
+除内置「分享」外，任意自定义工具按钮标记 `triggerSelection: true` 后，点击即可复用同一套多选流程（勾选消息 → `SelectionFooter` 确认），确认时同样触发 `confirmShare`。配合 `messageTools` / `updateTools`（合并规则见 [MessageContainer · 自定义消息工具栏](/components/setup/message-container)）即可扩展如「保存」「收藏到空间」等批量操作。
+
+```vue
+<template>
+  <ChatContainer
+    v-model="inputValue"
+    :messages="messages"
+    message-status="complete"
+    :message-tools="customMessageTools"
+    :on-agent-action="handleAgentAction"
+    @confirm-share="handleConfirmShare"
+  />
+</template>
+
+<script setup lang="ts">
+  import { DownloadIcon, type IToolBtn, type Message } from '@blueking/chat-x';
+
+  const customMessageTools: IToolBtn[] = [
+    // 追加「保存」按钮，点击进入多选态；确认走 confirmShare
+    { id: 'save', name: '保存', description: '保存该回答', icon: DownloadIcon, triggerSelection: true },
+  ];
+
+  const handleConfirmShare = (selectedMessages: Message[], source?: IToolBtn) => {
+    if (source?.id === 'save') {
+      // 处理「保存」批量确认
+    }
+  };
+</script>
+```
+
+> `triggerSelection` 的按钮不会调用 `onAgentAction`，而是直接进入多选态；未标记该字段（且非 `share`）的按钮仍走 `onAgentAction`。
+
 **渲染效果**（点击 AI 回复工具栏中的「分享」按钮进入多选模式）
 
 **分享流程**：
 
-1. 用户点击消息工具栏中的「分享」按钮
+1. 用户点击消息工具栏中的「分享」按钮（或任意 `triggerSelection: true` 的自定义按钮）
 2. 进入多选模式，用户勾选要分享的消息
 3. 底部 `SelectionFooter` 提供全选、取消、确认操作
-4. 确认后触发 `confirmShare` 事件，携带选中的消息列表
+4. 确认后触发 `confirmShare` 事件，携带选中的消息列表与触发按钮对象（`source`）
+
+## 模型选择
+
+`ChatContainer` 将 `models`、`v-model:selected-model` 与 `@model-change` 透传至内部 [ChatInput](/components/input/chat-input)。传入 `models` 后，发送按钮左侧展示 [ModelSelector](/components/input/model-selector)；选中值为模型的 `llm_name`，发送时可读取当前 `selectedModel`。
+
+```vue
+<template>
+  <ChatContainer
+    v-model="inputValue"
+    v-model:selected-model="selectedModel"
+    :messages="messages"
+    message-status="complete"
+    :models="models"
+    :on-send-message="handleSendMessage"
+    @model-change="handleModelChange"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatContainer, type IModelOption, type Message, type TagSchema } from '@blueking/chat-x';
+
+  const inputValue = ref('');
+  // 选中值为 llm_name
+  const selectedModel = ref('GPT-4');
+  const messages = ref<Message[]>([]);
+  const models: IModelOption[] = [
+    { id: 1, llm_name: 'GPT-4', property: { support_thinking: true } },
+    { id: 2, llm_name: 'Claude 3', property: { support_thinking_quick: true } },
+    { id: 3, llm_name: 'DeepSeek', property: { support_vision: true } },
+  ];
+
+  const handleSendMessage = async (content: string, docSchema: TagSchema) => {
+    // 发送时可读取 selectedModel.value
+  };
+  const handleModelChange = (model: IModelOption) => {
+    console.log('切换模型:', model);
+  };
+</script>
+```
+
+**渲染效果**（输入区发送按钮左侧可切换模型）
 
 ## 快捷指令
 
@@ -543,29 +695,33 @@ ai-chat-container（:data-ai-size="size"）
 
 ChatContainer 的 Props 继承自 `ChatInputProps` 和 `MessageContainerProps`（排除 `enableSelection` 和 `messageGroups`），另外新增：
 
-| 属性名             | 类型                                                                         | 默认值   | 说明                                                                                                                                          |
-| ------------------ | ---------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| chatLoading                 | `boolean`                                                                    | —        | 整体加载状态，`true` 时显示 Loading 遮罩                                                                                                      |
-| commonTippyOptions          | `AITippyProps`                                                               | —        | 通用 Tippy 配置（`appendTo` / `placement` / `zIndex`），传入的选项会注入到所有使用 `v-overflow-tips` 的子组件中                                 |
-| executionTabVisible         | `boolean`                                                                    | `true`   | 「执行情况」Tab 是否展示；为 `false` 时从 Tab 栏隐藏，若其正被选中则自动切到首个可见 Tab，内容不再渲染                                          |
-| getSideRenderComponent      | `(h, props?) => VNode \| undefined`                                          | —        | 自定义侧栏内容区渲染；未返回时使用 `selectedTab.data.component`                                                                               |
-| getSideTabRenderComponent   | `(h, tab, { removeCustomTab }) => VNode \| undefined`                        | —        | 自定义侧栏 Tab 标签渲染；未返回时使用默认图标 + 文案 + 关闭按钮                                                                               |
-| openingRemark               | `string`                                                                     | —        | 开场白，无消息时显示，支持 Markdown                                                                                                           |
-| placement          | `'left' \| 'right'`                                                          | `'left'` | 侧边栏位置                                                                                                                                    |
-| size               | `'normal' \| 'small'`                                                        | `'small'` | 字号主题档位：`small` 为 12px 基准，`normal` 为 14px 基准；根节点设置 `data-ai-size` 并注入 `useGlobalConfig`                                |
-| resizeProps        | `{ disabled?: boolean; initialDivide?: number \| string; max?: number; min?: number }` | —        | 透传给内部 `ResizeLayout` 的可选配置，与默认 `collapsible: false`、`immediate: true`、`min: 400` 合并；`placement` 始终取自本组件 `placement`；`initialDivide` 可为像素数字或百分比等字符串（与 bkui ResizeLayout 一致） |
-| onCustomTabChange  | `(tab: CustomTab) => Promise<any>`                                           | —        | 自定义 Tab 切换回调，返回值作为 Tab 组件 props                                                                                                |
-
-> 完整 Props 列表请参考 [ChatInput](/components/input/chat-input) 和 [MessageContainer](/components/setup/message-container) 文档。
+| 属性名                    | 类型                                                                                     | 默认值    | 说明                                                                                                                                 |
+| ------------------------- | ---------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| chatLoading               | `boolean`                                                                                | —         | 整体加载状态，`true` 时显示 Loading 遮罩                                                                                             |
+| commonTippyOptions        | `AITippyProps`                                                                           | —         | 通用 Tippy 配置，注入到所有使用 `v-overflow-tips` 的子组件                                                                           |
+| executionTabVisible       | `boolean`                                                                                | `true`    | 「执行情况」Tab 是否展示；为 `false` 时从 Tab 栏隐藏，若正被选中则切到首个可见 Tab                                                   |
+| getSideRenderComponent    | `(h, props?) => VNode \| undefined`                                                      | —         | 自定义侧栏内容区渲染；未返回时使用 `selectedTab.data.component`                                                                      |
+| getSideTabRenderComponent | `(h, tab, { removeCustomTab }) => VNode \| undefined`                                    | —         | 自定义侧栏 Tab 标签渲染；未返回时使用默认图标 + 文案 + 关闭按钮                                                                      |
+| models                    | `IModelOption[]`                                                                         | —         | 可选模型列表（继承自 ChatInput）；传入后在发送按钮左侧展示 ModelSelector                                                             |
+| openingRemark             | `string`                                                                                 | —         | 开场白，无消息时显示，支持 Markdown                                                                                                  |
+| placement                 | `'left' \| 'right'`                                                                      | `'left'`  | 侧边栏位置                                                                                                                           |
+| resizeProps               | `{ disabled?: boolean; initialDivide?: number \| string; max?: number; min?: number }`    | —         | 透传给内部 `ResizeLayout`；与默认 `collapsible: false`、`immediate: true`、`min: 400` 合并；`placement` 始终取自本组件。**数字型** `initialDivide` 还会作为内部侧栏宽度初值（驱动 `--resize-main-width`，并在展开时作为 `collapseChange` 的 `width`）；百分比等字符串则回退为 `400` |
+| 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`；未传则隐藏下载、预览无数据 |
+
+> 其余 Props（如 `messages`、`messageStatus`、`onSendMessage`、`shortcuts` 等）继承自 [ChatInput](/components/input/chat-input) 与 [MessageContainer](/components/setup/message-container)。
 
 ### v-model
 
-| 属性名           | 类型                  | 说明                                                         |
-| ---------------- | --------------------- | ------------------------------------------------------------ |
-| modelValue       | `string \| TagSchema` | 输入框内容，支持纯文本或标签结构                             |
-| selectedShortcut | `Shortcut \| null`    | 当前选中的快捷指令                                           |
-| cite             | `string`              | 引用内容                                                     |
-| renderMode       | `RenderMode`          | 渲染模式（默认 `Chat`）。`Share` 分享态开放侧栏只读查看（流程智能体详情/证据/执行情况），隐藏底部输入区与「重试/跳过」等交互；`Test` 模式隐藏分享按钮 |
+| 属性名           | 类型                  | 说明                                                                                                                                              |
+| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| modelValue       | `string \| TagSchema` | 输入框内容，支持纯文本或标签结构                                                                                                                  |
+| selectedShortcut | `Shortcut \| null`    | 当前选中的快捷指令                                                                                                                                |
+| cite             | `string`              | 引用内容                                                                                                                                          |
+| renderMode       | `RenderMode`          | 渲染模式（默认 `Chat`）。`Share` 开放侧栏只读查看并隐藏底部输入与交互操作；`Test` 隐藏分享按钮                                                    |
+| selectedModel    | `string`              | 当前选中模型的 `llm_name`，透传至 ChatInput 的 ModelSelector                                                                                      |
 
 ### Events
 
@@ -574,21 +730,22 @@ ChatContainer 的 Props 继承自 `ChatInputProps` 和 `MessageContainerProps`
 | stopStreaming  | —                                      | 点击「停止生成」按钮                 |
 | shortcutClose  | —                                      | 关闭快捷指令表单                     |
 | shortcutSubmit | `(formModel: Record<string, unknown>)` | 提交快捷指令表单                     |
-| confirmShare   | `(messages: Message[])`                | 确认分享，携带选中的消息             |
+| confirmShare   | `(messages: Message[], source?: IToolBtn)` | 确认分享/多选，携带选中的消息与触发按钮对象（`source`，用于区分 share/save 等场景） |
 | collapseChange | `(isCollapse: boolean, width: number)` | 侧边栏折叠/展开状态变化              |
 | selectShortcut | `(shortcut: Shortcut)`                 | 选择快捷指令（继承自 ChatInput）     |
 | deleteShortcut | —                                      | 删除已选快捷指令（继承自 ChatInput） |
+| modelChange    | `(model: IModelOption)`                | 切换模型（继承自 ChatInput）         |
 
 ### Slots
 
-| 插槽名            | 参数                                                                                                              | 说明                                                                                           |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| codeHeader        | `{ language: string; token: Token[] }`                                                                            | 代码块头部自定义操作区域，透传给 MessageRender → ContentRender → MarkdownContent → CodeContent |
-| default           | 消息列表相关绑定（messages 等）                                                                                   | 自定义消息列表区域                                                                             |
-| group             | `{ group: MessageGroup }`                                                                                         | 自定义单个消息组内容，透传至 MessageContainer 的 `#group`；替换默认 Checkbox、消息列表与工具栏   |
-| interruptQuestion | `{ question, qIndex, answer, setAnswer, confirm }`                                                                  | 自定义 UserQuestion 单题渲染，透传至输入区上方 UserQuestionCard 的 `#question`                 |
-| message           | `{ message, messageToolsStatus, onInterruptResume }`                                                              | 自定义单条消息渲染；自定义渲染中断消息时需继续透传 `onInterruptResume`                         |
-| welcome           | `{ openingRemark: string }`                                                                                       | 无消息时自定义欢迎页；传入则替换默认 Banner、标题与开场白区域（整块替换）                      |
+| 插槽名            | 参数                                                                                         | 说明                                                                                                     |
+| ----------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| codeHeader        | `{ language: string; token: Token[] }`                                                       | 代码块头部自定义操作区域（定义于类型；透传链路同 MessageRender）                                         |
+| default           | `{ messages, messageStatus, messageGroups, selectedUserMessages, messageToolsStatus, isShareMode, commonTippyOptions, handleAgentAction, onAgentFeedback, onInterruptResume, onUserAction, onUserInputConfirm, onUserShortcutConfirm }` | 自定义消息列表区域；未提供时渲染默认 `MessageContainer`                                                  |
+| group             | `{ group: MessageGroup }`                                                                    | 自定义单个消息组，透传至 MessageContainer `#group`；替换默认 Checkbox、消息列表与工具栏                  |
+| interruptQuestion | `{ question, qIndex, answer, setAnswer, confirm }`                                           | 自定义 UserQuestion 单题渲染，透传至 UserQuestionCard `#question`                                        |
+| message           | `{ message, messageToolsStatus, onInterruptResume }`                                         | 自定义单条消息；自定义中断消息时需继续透传 `onInterruptResume`                                           |
+| welcome           | `{ openingRemark?: string; welcomeTitle?: string }`                                          | 无消息时自定义欢迎页；传入则整块替换默认 Banner、标题与开场白                                            |
 
 ### Expose
 
@@ -633,7 +790,16 @@ ChatContainer 的 Props 继承自 `ChatInputProps` 和 `MessageContainerProps`
 ## 类型定义
 
 ```typescript
-import { ChatContainer, RenderMode, MessageRole, type CustomTab, type MessageGroup, type Shortcut, type Message } from '@blueking/chat-x';
+import {
+  ChatContainer,
+  RenderMode,
+  MessageRole,
+  type CustomTab,
+  type IModelOption,
+  type MessageGroup,
+  type Shortcut,
+  type Message,
+} from '@blueking/chat-x';
 
 // 消息组（由 useMessageGroup 生成）
 interface MessageGroup {
@@ -651,7 +817,33 @@ interface MessageGroup {
 interface CustomTab<T = Record<string, unknown>> {
   label: string;
   name: string;
-  data?: T & { messageUid?: string };
+  icon?: string;
+  order?: number; // 缺省 100；「执行情况」固定 0
+  visible?: boolean; // 缺省 true；false 时栏内隐藏，仍可程序化选中
+  closable?: boolean; // 缺省 true；「执行情况」强制不可关闭
+  data?: T & { messageUid?: string; component?: Component; props?: Record<string, unknown> };
+}
+
+// 模型选项（透传至 ChatInput / ModelSelector，贴合后端接口结构；能力标签由 property 派生）
+interface IModelOption {
+  id: number;
+  llm_code: string;
+  llm_name: string; // 展示名，同时作为选中值
+  llm_type: string;
+  space_auth_mode: string;
+  user_auth_mode: string;
+  max_token_size: number;
+  property: {
+    support_thinking?: boolean; // → 深度思考
+    support_thinking_quick?: boolean; // → 快速思考
+    support_vision?: boolean; // → 图生文
+    [key: string]: unknown;
+  };
+  icon?: string;
+  description?: string;
+  base_model?: string;
+  tag_names?: string[];
+  disabled?: boolean; // 前端扩展字段
 }
 
 // 快捷指令
@@ -666,10 +858,11 @@ interface Shortcut {
 
 - [MessageContainer](/components/setup/message-container) — 消息列表区域
 - [ChatInput](/components/input/chat-input) — 输入与快捷指令
+- [ModelSelector](/components/input/model-selector) — 模型选择器（透传 `models` / `selectedModel`）
 - [ShortcutRender](/components/input/shortcut-render) — 快捷指令表单
 - [ExecutionSummary](/components/agent/execution-summary) — 执行摘要侧栏
 - [SelectionFooter](/components/input/selection-footer) — 多选操作栏
-- [ToolBtn](/components/feedback/tool-btn) — 侧栏全屏按钮（自定义插槽）
+- [ToolBtn](/components/feedback/tool-btn) — 侧栏全屏按钮
 - [useFullScreen](/composables/use-full-screen) — 侧栏全屏控制
 - [useGlobalConfig](/composables/use-global-config) — 注入 `size` 与 `supportUpload`
 - [主题配置](/theme/theme) — 字号主题 CSS 变量

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

@@ -8,6 +8,7 @@
 - **shortcut-btn** — 已选快捷指令以单按钮形式展示并可关闭
 - **shortcut-render** — 快捷指令含 components 时由外层唤起表单渲染
 - **chat-container** — 顶层聊天布局中作为输入区子组件
+- **model-selector** — 传入 models 后在发送按钮左侧默认展示模型选择器
 - **cite-content** — 消息引用区展示选中的上下文片段
 
 ---
@@ -38,6 +39,7 @@ ai-chat-input-container
         ├── FileUploadBtn（仅当 supportUpload 为 true 时显示，在 slot#attachment 外部）
         ├── 分隔线（仅当 supportUpload 为 true 且有快捷指令时显示）
         ├── slot#attachment（默认：ShortcutBtns 或已选 ShortcutBtn + 关闭图标）
+        ├── slot#before-send（默认：传入 models 时渲染 ModelSelector）
         └── slot#send-icon（默认：发送/停止图标，仅替换图标，按钮容器保留）
 ```
 
@@ -498,6 +500,57 @@ const handleSendMessage = async (
 
 **渲染效果**（顶部自定义模型信息与中断提示）
 
+## 模型选择
+
+传入 `models` 后，会在发送按钮左侧展示 [ModelSelector](/components/input/model-selector)。选中值（模型的 `llm_name`）通过 `v-model:selected-model` 双向绑定，`@model-change` 可获取完整模型对象。能力标签由组件依据 `property` 自动派生。
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    v-model:selected-model="selectedModel"
+    :message-status="messageStatus"
+    :models="models"
+    :on-send-message="handleSendMessage"
+    @model-change="handleModelChange"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatInput, MessageStatus, type IModelOption, type TagSchema } from '@blueking/chat-x';
+
+  const inputValue = ref('');
+  // 选中值为 llm_name
+  const selectedModel = ref('GPT-4');
+  const messageStatus = ref(MessageStatus.Complete);
+  const models: IModelOption[] = [
+    { id: 1, llm_name: 'GPT-4', property: { support_thinking: true } },
+    { id: 2, llm_name: 'Claude 3', property: {} },
+  ];
+
+  const handleSendMessage = async (content: string, docSchema: TagSchema) => {
+    /* 发送时可读取 selectedModel.value */
+  };
+
+  const handleModelChange = (model: IModelOption) => {
+    console.log('切换模型:', model);
+  };
+</script>
+```
+
+也可通过 `#model-selector` 插槽完全自定义选择器，插槽参数为 `{ models, selectedModel }`：
+
+```vue
+<template>
+  <ChatInput v-model="inputValue" :models="models">
+    <template #model-selector="{ models, selectedModel }">
+      <span>当前：{{ selectedModel || '未选择' }}（共 {{ models.length }} 个）</span>
+    </template>
+  </ChatInput>
+</template>
+```
+
 ## Expose（模板引用）
 
 通过 `ref` 获取组件实例后可调用以下方法：
@@ -532,12 +585,14 @@ const handleSendMessage = async (
 | 属性名             | 类型                                                                       | 默认值   | 必填 | 说明                                                    |
 | ------------------ | -------------------------------------------------------------------------- | -------- | ---- | ------------------------------------------------------- |
 | modelValue         | `string \| TagSchema`                                                      | -        | ✅   | 编辑器的值，支持 `v-model`                              |
+| selectedModel      | `string`                                                                   | -        | -    | 当前选中模型的 `llm_name`，支持 `v-model:selected-model` |
 | messageStatus      | `MessageStatus`                                                            | -        | -    | 消息状态，控制按钮；输入为空时内部强制 `disabled`       |
 | cite               | `string`                                                                   | `''`     | -    | 引用内容，支持 `v-model:cite`，不为空时显示引用区       |
 | skills             | `ISkillListItem[]`                                                         | `[]`     | -    | Skill 列表，输入 `/` 触发，选中后插入 Skill 标签        |
 | prompts            | `string[]`                                                                 | `[]`     | -    | Prompt 模板列表，输入 `\` 触发                          |
 | resources          | `IAiSlashMenuItem[]`                                                       | `[]`     | -    | 资源列表，输入 `@` 触发，按 `type` 分组展示             |
 | shortcuts          | `Shortcut[]`                                                               | -        | -    | 快捷指令列表，显示在底部工具栏                          |
+| models             | `IModelOption[]`                                                           | -        | -    | 可选模型列表，传入后在发送按钮左侧展示模型选择器        |
 | shortcutId         | `string`                                                                   | -        | -    | 当前选中的快捷指令 ID，匹配时列表收起为已选样式         |
 | placeholder        | `string`                                                                   | 见默认值 | -    | 编辑器占位符，支持多行                                  |
 | inputMaxHeight     | `number`                                                                   | `200`    | -    | 框体最大高度（px），有文件时自动加上文件预览区高度      |
@@ -563,6 +618,7 @@ const handleSendMessage = async (
 | 事件名            | 参数                                                                     | 触发时机                                                  |
 | ----------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
 | update:modelValue | `(value: string \| TagSchema, selectedResourceList: IAiSlashMenuItem[])` | 编辑器值变化时触发；第二个参数为当前已选中的 `@` 资源列表 |
+| modelChange       | `(model: IModelOption)`                                                  | 用户切换模型时触发                                        |
 | selectShortcut    | `(shortcut: Shortcut)`                                                   | 点击底部快捷指令按钮                                      |
 | deleteShortcut    | -                                                                        | 点击已选快捷指令旁的关闭按钮                              |
 
@@ -575,6 +631,7 @@ const handleSendMessage = async (
 | input-header | -                                  | 框体内顶部，替换引用区（`CiteContent`）                    |
 | files        | `{ files: Partial<UploadFile>[] }` | 文件预览区                                                 |
 | attachment   | -                                  | 底部快捷指令区，`FileUploadBtn` 在其左侧，不受此 slot 影响 |
+| model-selector | `{ models: IModelOption[]; selectedModel: string \| undefined }` | 发送按钮左侧模型选择区，默认渲染 ModelSelector             |
 | send-icon    | -                                  | 发送按钮内图标，按钮的点击逻辑和样式仍由组件控制           |
 
 ### Expose