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

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

@@ -301,6 +301,51 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 
 连续多轮问答，组件按角色自动分组，每个 AI 组独立显示工具栏：
 
+## 自定义消息工具栏
+
+`messageTools`（左侧）与 `updateTools`（右侧反馈区）用于在**内置工具的基础上做增量定制**，无需重写整份列表。二者分别与内置 `CONST_MESSAGE_TOOLS`、`CONST_UPDATE_TOOLS` 按 `id` 合并，规则如下：
+
+- **覆盖**：`id` 命中内置项时，做字段级浅合并（仅覆盖传入的字段，其余保留），不新增条目
+- **追加**：`id` 为内置列表中不存在的新值时，追加到该组末尾（如自定义「保存」「收藏」按钮）
+- **隐藏**：传入 `{ id: 'xxx', hidden: true }` 可移除对应内置项（如隐藏「分享」）
+- **自定义图标**：通过 `icon`（组件/VNode）为自定义按钮提供图标，优先级高于内置 `ToolIconsMap`
+- 不传 `messageTools` / `updateTools` 时，各自使用内置默认列表
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :message-groups="messageGroups"
+    message-status="complete"
+    :message-tools="customMessageTools"
+    :update-tools="customUpdateTools"
+    :on-agent-action="handleAgentAction"
+    @stop-streaming="handleStopStreaming"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageContainer, DownloadIcon, type IToolBtn, type Message } from '@blueking/chat-x';
+
+  const customMessageTools: IToolBtn[] = [
+    { id: 'save', name: '保存', description: '保存该回答', icon: DownloadIcon }, // 追加新按钮
+    { id: 'copy', description: '复制全文' }, // 覆盖内置 copy 的 description
+    { id: 'share', hidden: true }, // 隐藏内置「分享」
+  ];
+  const customUpdateTools: IToolBtn[] = [
+    { id: 'collect', name: '收藏', description: '收藏到我的空间', icon: DownloadIcon },
+  ];
+
+  const handleAgentAction = async (tool: IToolBtn, messages: Message[]) => {
+    if (tool.id === 'save') {
+      // 处理保存
+    }
+  };
+</script>
+```
+
+> **合并优先级**：`RenderMode.Test` 下仍会额外过滤掉「分享」按钮（即便合并后存在）；即测试模式对 `share` 的过滤在自定义合并之后生效。
+
 ## 工具栏状态控制
 
 通过 `messageToolsStatus` 控制消息工具栏的显示状态。常见用法：流式输出期间禁用工具栏：
@@ -501,6 +546,8 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 | messages                 | `Message[]`                                                                                  | —       | **必填**，消息列表                                                                                                                       |
 | messageGroups            | `MessageGroup[]`                                                                             | —       | 预计算的消息分组；传入时跳过内部分组逻辑，由 `ChatContainer` 通过 `useMessageGroup` 提供                                                 |
 | messageStatus            | `MessageStatus`                                                                              | —       | 当前整体消息状态，控制底部「停止生成」按钮显示；`ChatContainer` 会结合末尾 Loading 占位推导 `fetching` 等再传入                                                                                                   |
+| messageTools             | `IToolBtn[]`                                                                                 | —       | AI 消息左侧工具（复制/引用等）的自定义配置；按 `id` 与内置 `CONST_MESSAGE_TOOLS` 合并（覆盖同 id、追加新 id、`hidden` 过滤），详见「自定义消息工具栏」 |
+| updateTools              | `IToolBtn[]`                                                                                 | —       | AI 消息右侧反馈工具（点赞/踩/删除等）的自定义配置；按 `id` 与内置 `CONST_UPDATE_TOOLS` 合并，规则同上                                     |
 | messageToolsStatus       | `MessageToolsStatus`                                                                         | —       | 工具栏状态，透传给 `MessageTools` 和 `MessageRender`                                                                                     |
 | messageToolsTippyOptions | `AITippyProps`                                                                               | —       | 透传给 `MessageTools` 和 `MessageRender`（进而透传给 `UserMessage` 的工具栏）的 Tippy 配置，用于自定义 tooltip 挂载点、位置等（如 `appendTo`、`placement`、`zIndex`） |
 | enableSelection          | `boolean`                                                                                    | `false` | 是否启用多选模式                                                                                                                         |

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

@@ -361,11 +361,15 @@ const CONST_UPDATE_TOOLS = [
 
 ```typescript
 import { MessageToolsStatus, type IToolBtn } from '@blueking/chat-x';
+import type { Component, VNode } from 'vue';
 
 interface IToolBtn {
-  id?: keyof typeof ToolIconsMap; // 工具唯一标识；与 ToolIconsMap 匹配时显示内置图标，否则显示 name 文本
+  id?: (string & {}) | ToolIcons; // 工具唯一标识；命中 ToolIconsMap 显示内置图标，否则显示 name 文本；支持业务自定义字符串
   name?: string; // 工具名称，无对应图标时显示；也用作 tooltip fallback
   description?: string; // tooltip 文本
+  icon?: Component | VNode; // 自定义图标（组件/VNode），优先级高于内置 ToolIconsMap[id]
+  hidden?: boolean; // 按 id 合并时隐藏该按钮（仅在 MessageContainer/ChatContainer 合并语义下生效）
+  triggerSelection?: boolean; // 标记点击后进入多选态（复用 share 选择流程），确认走 confirmShare
 }
 
 enum MessageToolsStatus {

package/dist/mcp/generated/docs/model-selector.md

@@ -0,0 +1,157 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+聊天输入区的模型下拉选择器，支持搜索过滤、能力标签与键盘导航。 源码位置：src/components/chat-input/model-selector/model-selector.vue。
+
+### 关联组件
+- **chat-input** — 传入 models 后在发送按钮左侧默认渲染
+- **input-attachment** — 通过 before-send 插槽与发送按钮成组布局
+
+---
+<!-- FULL DOC -->
+
+# ModelSelector 模型选择器
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-input/model-selector/model-selector.vue`
+- **能力域**：输入交互
+- **能力说明**：基于 Tippy 下拉的模型选择器，包含触发器、搜索面板与能力标签展示；数据过滤逻辑由 `useModelSelector` composable 承担。
+
+> **能力域**：输入交互
+
+可在 [ChatInput](/components/input/chat-input) 传入 `models` 后自动出现在发送按钮左侧，也可单独使用。
+
+## 组件结构
+
+```
+ModelSelector（Tippy 容器，theme: ai-model-selector）
+├── ModelSelectorTrigger（触发器：图标 + 名称 + 箭头）
+└── ModelSelectorPanel（下拉面板）
+    ├── 搜索框（展开后自动聚焦）
+    └── 模型列表（支持键盘导航、选中态、禁用态、能力标签）
+```
+
+## 基础用法
+
+选中值为模型的 `llm_name`；能力标签由组件依据 `property`（`support_thinking` / `support_thinking_quick` / `support_vision`）自动派生，无需调用方传入。
+
+```vue
+<template>
+  <ModelSelector
+    v-model="selectedModel"
+    :models="models"
+    @change="handleModelChange"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ModelSelector, type IModelOption } from '@blueking/chat-x';
+
+  // 选中值为 llm_name
+  const selectedModel = ref('DeepSeek-V4-Pro-Online-32k');
+  const models: IModelOption[] = [
+    {
+      id: 119,
+      llm_code: 'DeepSeek-V4-Pro-Online-32k',
+      llm_name: 'DeepSeek-V4-Pro-Online-32k',
+      llm_type: 'chat.completion',
+      space_auth_mode: 'APPLY',
+      user_auth_mode: 'PUBLIC',
+      max_token_size: 4096,
+      icon: 'https://example.com/deepseek.png',
+      description: 'DeepSeek-V4-Pro 旗舰版本，支持超长上下文与复杂任务处理',
+      base_model: 'deepseek',
+      tag_names: [],
+      // support_thinking → 深度思考、support_vision → 图生文
+      property: { support_thinking: true, support_vision: true, max_model_len: 32000 },
+    },
+  ];
+
+  const handleModelChange = (model: IModelOption) => {
+    console.log('选中模型:', model);
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名            | 类型                                                                       | 默认值           | 说明                                   |
+| ----------------- | -------------------------------------------------------------------------- | ---------------- | -------------------------------------- |
+| disabled          | `boolean`                                                                  | `false`          | 是否禁用整个选择器                     |
+| models            | `IModelOption[]`                                                           | `[]`             | 可选模型列表                           |
+| placeholder       | `string`                                                                   | `选择模型`       | trigger 无选中时的占位文案             |
+| searchPlaceholder | `string`                                                                   | `搜索模型关键字` | 搜索框占位文案                         |
+| tippyOptions      | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | —                | 透传给 Tippy 的额外配置                |
+
+### v-model
+
+| 属性名 | 类型     | 说明                          |
+| ------ | -------- | ----------------------------- |
+| —      | `string` | 当前选中模型的 `llm_name` 值 |
+
+### Events
+
+| 事件名 | 参数                    | 说明                 |
+| ------ | ----------------------- | -------------------- |
+| change | `(model: IModelOption)` | 用户选中模型时触发   |
+
+## 类型定义
+
+```typescript
+import type { IModelCapability, IModelOption, IModelProperty, ModelCapabilityTheme } from '@blueking/chat-x';
+
+type ModelCapabilityTheme = 'default' | 'primary' | 'success' | 'warning';
+
+// 能力标签由组件依据 property 派生（文案走内置 i18n）
+interface IModelCapability {
+  theme?: ModelCapabilityTheme;
+  text: string;
+}
+
+// 模型能力属性，决定派生出的能力标签
+interface IModelProperty {
+  agent_type?: string;
+  default?: boolean;
+  is_self_host?: boolean;
+  max_model_len?: number;
+  support_summary?: boolean;
+  support_thinking?: boolean; // → 深度思考
+  support_thinking_quick?: boolean; // → 快速思考
+  support_tools?: boolean;
+  support_vision?: boolean; // → 图生文
+  support_window?: boolean;
+}
+
+// 模型选项，贴合后端模型接口结构
+interface IModelOption {
+  base_model?: string;
+  description?: string; // 选项 hover 的 title 提示
+  disabled?: boolean; // 前端扩展字段，禁用项不可选中
+  icon?: string;
+  id: number;
+  llm_code: string;
+  llm_name: string; // 展示名，同时作为选中值
+  llm_type: string;
+  max_token_size: number;
+  property: IModelProperty;
+  space_auth_mode: string;
+  tag_names?: string[];
+  user_auth_mode: string;
+}
+```
+
+## 注意事项
+
+1. `models` 为空或 `disabled` 为 `true` 时，下拉不会展开。
+2. 选中值为模型的 `llm_name`；能力标签由组件依据 `property` 的 `support_thinking` / `support_thinking_quick` / `support_vision` 派生，文案走内置 i18n。
+3. `description` 会作为选项 hover 的 `title` 提示展示。
+4. 展开面板后会自动聚焦搜索框；列表支持键盘上下选择与 Enter 确认（复用 `useMenuKeydown`）。
+
+## 关联组件
+
+- [ChatInput](/components/input/chat-input)：传入 `models` 后默认在发送按钮左侧渲染本组件，也可通过 `#model-selector` 插槽完全自定义。
+- [ChatContainer](/components/setup/chat-container)：透传 `models` 与 `v-model:selected-model`，并向上 emit `modelChange`。

package/dist/mcp/generated/docs/tool-btn.md

@@ -30,8 +30,9 @@ div.ai-tool-btn（v-tippy，flex，min-width: 20px，height: 20px，border-radiu
   disabled=true → .is-disabled（color: #979ba5; cursor: not-allowed）
   :not(.is-disabled):hover → color: #4d4f56; background: #eaebf0
   │
-  └── <slot>（默认内容，可完全自定义）
-        ├── [id && id in ToolIconsMap] → <component :is="ToolIconsMap[id]" />（SVG 图标）
+  └── <slot>（默认内容，可完全自定义；优先级最高）
+        ├── [icon] → <component :is="icon" />（自定义图标组件/VNode，优先级高于内置图标）
+        ├── [id && id in ToolIconsMap] → <component :is="ToolIconsMap[id]" />（内置 SVG 图标）
         └── [其他] → <div>{{ name }}</div>（文本回退，XSS 安全）
 
 Tippy：content=description, theme='ai-chat-box', disabled=true 时 onShow 返回 false 不显示
@@ -195,6 +196,28 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 
 `id` 不在 `ToolIconsMap` 时渲染 `name` 文本，适用于自定义扩展场景：
 
+## 自定义图标（icon 属性）
+
+当内置 `ToolIconsMap` 未覆盖所需图标时，可通过 `icon` 传入自定义图标组件或 VNode（如业务新增的「保存」按钮）。`icon` 的渲染优先级高于内置图标，因此即便 `id` 命中内置图标，也会以 `icon` 为准。
+
+```vue
+<template>
+  <ToolBtn
+    id="save"
+    name="保存"
+    description="保存该回答"
+    :icon="DownloadIcon"
+    @click="handleClick"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ToolBtn, DownloadIcon } from '@blueking/chat-x';
+</script>
+```
+
+> 优先级从高到低：默认插槽 `>` `icon` 属性 `>` 内置 `ToolIconsMap[id]` `>` `name` 文本回退。
+
 ## 自定义插槽内容
 
 通过默认插槽可完全替换内置图标/文本，适用于预置 `ToolIconsMap` 未覆盖的图标场景（如侧栏全屏按钮）：
@@ -225,9 +248,10 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 
 | 属性名       | 类型                                                                       | 必填 | 默认值 | 说明                                                                                                               |
 | ------------ | -------------------------------------------------------------------------- | ---- | ------ | ------------------------------------------------------------------------------------------------------------------ |
-| id           | `keyof typeof ToolIconsMap`                                                | 否   | —      | 按钮标识；在 `ToolIconsMap` 中时渲染对应 SVG 图标，否则渲染 `name` 文本；使用插槽自定义内容时可省略                  |
+| id           | `(string & {}) \| ToolIcons`                                               | 否   | —      | 按钮标识；命中 `ToolIconsMap` 时渲染对应 SVG 图标，否则渲染 `name` 文本；支持业务自定义任意字符串（如 `save`）      |
 | name         | `string`                                                                   | 否   | —      | 按钮名称；`id` 无对应图标时作为文本内容渲染                                                                        |
 | description  | `string`                                                                   | 否   | —      | Tippy tooltip 内容；`disabled=true` 时不显示 tooltip                                                               |
+| icon         | `Component \| VNode`                                                        | 否   | —      | 自定义图标组件或 VNode；优先级高于内置 `ToolIconsMap[id]`，低于默认插槽                                             |
 | active       | `boolean`                                                                  | 否   | —      | 激活态；`true` 时追加 `.is-active`（字色由 `id` 决定：`like`/`activeLike` 为蓝色 `#3a84ff`，其他为红色 `#E71818`） |
 | disabled     | `boolean`                                                                  | 否   | —      | 禁用态；`true` 时追加 `.is-disabled`，阻止 click 事件，隐藏 tooltip                                                |
 | tippyOptions | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | 否   | —      | 自定义 Tippy 配置，与内部默认配置合并；可用于控制 `content`、`appendTo`、`placement` 等                            |
@@ -247,11 +271,16 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 ## 类型定义
 
 ```typescript
+import type { Component, VNode } from 'vue';
+
 // 来自 @blueking/chat-x 导出
 interface IToolBtn {
-  id?: keyof typeof ToolIconsMap; // 预置 ID；省略时走 name 文本或插槽
+  id?: (string & {}) | ToolIcons; // 内置 ID 保留自动补全，同时允许业务自定义任意字符串（如 'save'）
   name?: string;
   description?: string;
+  icon?: Component | VNode; // 自定义图标，优先级高于内置 ToolIconsMap
+  hidden?: boolean; // 按 id 合并时隐藏该按钮（如 { id: 'share', hidden: true } 移除内置项）
+  triggerSelection?: boolean; // 标记点击后进入多选态（复用 share 选择流程），确认走 confirmShare
 }
 
 // ToolBtn 完整 Props

package/dist/mcp/generated/index.json

@@ -1,6 +1,6 @@
 {
   "version": "2.0.0",
-  "generatedAt": "2026-07-16T12:12:34.511Z",
+  "generatedAt": "2026-07-27T02:31:49.169Z",
   "domains": {
     "setup": {
       "label": "对话搭建",
@@ -52,6 +52,7 @@
         "file-upload-btn",
         "input-attachment",
         "input-info-alert",
+        "model-selector",
         "selection-footer",
         "shortcut-btn",
         "shortcut-btns",
@@ -787,6 +788,10 @@
           "slug": "chat-container",
           "relation": "顶层聊天布局中作为输入区子组件"
         },
+        {
+          "slug": "model-selector",
+          "relation": "传入 models 后在发送按钮左侧默认展示模型选择器"
+        },
         {
           "slug": "cite-content",
           "relation": "消息引用区展示选中的上下文片段"
@@ -834,6 +839,25 @@
       "docFile": "docs/input-info-alert.md",
       "domain": "input"
     },
+    {
+      "name": "ModelSelector 模型选择器",
+      "slug": "model-selector",
+      "kind": "component",
+      "description": "聊天输入区的模型下拉选择器，支持搜索过滤、能力标签与键盘导航。",
+      "aiSummary": "聊天输入区的模型下拉选择器，支持搜索过滤、能力标签与键盘导航。 源码位置：src/components/chat-input/model-selector/model-selector.vue。",
+      "relatedComponents": [
+        {
+          "slug": "chat-input",
+          "relation": "传入 models 后在发送按钮左侧默认渲染"
+        },
+        {
+          "slug": "input-attachment",
+          "relation": "通过 before-send 插槽与发送按钮成组布局"
+        }
+      ],
+      "docFile": "docs/model-selector.md",
+      "domain": "input"
+    },
     {
       "name": "SelectionFooter 多选操作栏",
       "slug": "selection-footer",
@@ -1431,8 +1455,8 @@
       "name": "ChatContainer 聊天容器",
       "slug": "chat-container",
       "kind": "component",
-      "description": "完整对话容器，组合消息列表、输入区、快捷指令、执行摘要、分享选择和自定义 Tab。",
-      "aiSummary": "完整对话容器，组合消息列表、输入区、快捷指令、执行摘要、分享选择和自定义 Tab。 源码位置：src/components/chat-container/chat-container.vue。",
+      "description": "完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。",
+      "aiSummary": "完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。 透传 models / selectedModel；支持 welcomeTitle 与 #welcome。 源码位置：src/components/chat-container/chat-container.vue。",
       "relatedComponents": [
         {
           "slug": "message-container",
@@ -1442,6 +1466,10 @@
           "slug": "chat-input",
           "relation": "对话输入与快捷指令入口"
         },
+        {
+          "slug": "model-selector",
+          "relation": "透传 models / selectedModel，在输入区展示模型选择器"
+        },
         {
           "slug": "shortcut-render",
           "relation": "快捷指令表单浮层"

package/dist/types/tool.d.ts

@@ -1,4 +1,5 @@
-import type { ToolIconsMap } from '../icons/tools';
+import type { Component, VNode } from 'vue';
+import type { ToolIcons } from '../icons/tools';
 import type { TippyOptions } from 'vue-tippy';
 export declare enum MessageToolsStatus {
     Disabled = "disabled",// 禁用
@@ -7,6 +8,9 @@ export declare enum MessageToolsStatus {
 export type AITippyProps = Partial<Pick<TippyOptions, 'appendTo' | 'placement' | 'zIndex'>>;
 export interface IToolBtn {
     description?: string;
-    id?: keyof typeof ToolIconsMap;
+    hidden?: boolean;
+    icon?: Component | VNode;
+    id?: (string & {}) | ToolIcons;
     name?: string;
+    triggerSelection?: boolean;
 }

package/package.json

@@ -1,8 +1,26 @@
 {
   "name": "@blueking/chat-x",
-  "version": "0.0.47-beta.4",
+  "version": "0.0.48-beta.1",
   "description": "蓝鲸智云 AI Chat 组件库 —— 遵循 AG-UI，为 AI Agent 和人类开发者共同设计的对话 UI 组件库。",
   "main": "index.js",
+  "scripts": {
+    "prepublishOnly": "vite --config vite.config.ts build && pnpm dts && pnpm mcp:build",
+    "dev": "vite --config vite.config.ts",
+    "dts": "vue-tsc --project tsconfig.dts.json",
+    "build": "vitest && vite --config vite.config.ts build && pnpm dts",
+    "preview": "vite --config vite.config.ts build --mode preview && pnpm dts",
+    "lint:script": "eslint . --ext .vue,.ts --fix",
+    "lint:style": "stylelint \"**/*.{scss,css,vue}\" --fix",
+    "lint:all": "pnpm lint:script && pnpm lint:style",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "wiki:dev": "vitepress dev wikis",
+    "wiki:build": "vitepress build wikis",
+    "mcp:build:index": "tsx mcp/scripts/build-index.ts",
+    "mcp:build": "tsc -p mcp/tsconfig.json && pnpm mcp:build:index",
+    "mcp:start": "node dist/mcp/index.js",
+    "mcp:dev": "tsx mcp/src/index.ts"
+  },
   "bin": {
     "chat-x-mcp": "dist/mcp/index.js"
   },
@@ -50,6 +68,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@blueking/chat-helper": "workspace:*",
     "@types/katex": "^0.16.7",
     "@types/lodash": "^4.17.23",
     "@types/markdown-it": "^14.1.2",
@@ -78,24 +97,6 @@
     "vite-bundle-analyzer": "^1.3.2",
     "vitepress": "2.0.0-alpha.16",
     "vitest": "^4.0.18",
-    "vue-tsc": "^3.1.4",
-    "@blueking/chat-helper": "0.0.12-beta.10"
-  },
-  "scripts": {
-    "dev": "vite --config vite.config.ts",
-    "dts": "vue-tsc --project tsconfig.dts.json",
-    "build": "vitest && vite --config vite.config.ts build && pnpm dts",
-    "preview": "vite --config vite.config.ts build --mode preview && pnpm dts",
-    "lint:script": "eslint . --ext .vue,.ts --fix",
-    "lint:style": "stylelint \"**/*.{scss,css,vue}\" --fix",
-    "lint:all": "pnpm lint:script && pnpm lint:style",
-    "test": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "wiki:dev": "vitepress dev wikis",
-    "wiki:build": "vitepress build wikis",
-    "mcp:build:index": "tsx mcp/scripts/build-index.ts",
-    "mcp:build": "tsc -p mcp/tsconfig.json && pnpm mcp:build:index",
-    "mcp:start": "node dist/mcp/index.js",
-    "mcp:dev": "tsx mcp/src/index.ts"
+    "vue-tsc": "^3.1.4"
   }
 }