@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

package/skills/blueking-chat-x/references/components/message-tools.md

@@ -0,0 +1,427 @@
+# MessageTools 消息工具栏
+
+> 能力域：工具与反馈 ｜ 导入：`import { MessageTools } from '@blueking/chat-x'` ｜ since 1.0.0
+
+消息悬浮工具栏，组合复制、删除、反馈等工具按钮；提供 prepend / append 两端插槽承载消息时间等附加内容。 源码位置：src/components/message-tools/message-tools.vue。
+
+**关联**：tool-btn（普通工具项由 ToolBtn 渲染）、user-feedback（like/unlike 时弹出反馈表单）、delete-tool（id 为 delete 时替换为带确认的删除按钮）、message-time（通过 prepend / append 插槽嵌入消息时间）
+
+---
+
+# MessageTools 消息工具栏
+## 源码事实
+
+- **源码位置**：`src/components/message-tools/message-tools.vue`
+- **能力域**：工具与反馈
+- **能力说明**：消息悬浮工具栏，组合复制、删除、反馈等工具按钮。
+
+> **能力域**：工具与反馈
+
+AI 消息的操作工具栏组件，由**左侧消息工具区**和**右侧更新工具区**两部分组成，中间以分隔线分隔；两端另有 `prepend` / `append` 插槽用于挂载消息时间等附加内容。仅 `like` / `unlike` 按钮会弹出反馈表单（`UserFeedback`），其余按钮直接触发 `onAction`。
+
+## 组件结构
+
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│  .ai-message-tools-container（display: flex，gap: 4px）                 │
+│  ┌────────┐  ┌─────────────────────┐  │  ┌───────────────┐  ┌───────┐ │
+│  │#prepend│  │  messageTools        │  │  │  updateTools  │  │#append│ │
+│  │        │  │  copy rebuild share  │  │  │ like unlike…  │  │       │ │
+│  └────────┘  └─────────────────────┘  │  └───────────────┘  └───────┘ │
+│    插槽区          左侧区域         分隔线    右侧区域          插槽区   │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+- 分隔线（`.ai-divider`）与**右侧更新工具区**均仅在 `updateTools` 非空时渲染
+- `updateTools` 中 `id` 为 `like` / `unlike` 的按钮被 `Tippy` 弹窗包裹，点击后展示 `UserFeedback` 反馈表单
+- `updateTools` 中 `id` 为 `delete` 的按钮使用 `DeleteTool` 组件，点击后展示**确认删除弹窗**（含"删除"/"取消"按钮），确认后触发 `onAction`
+- `updateTools` 中其他按钮直接触发 `onAction`，不弹表单
+- `messageTools` 中 `id` 为 `delete` 的按钮同样使用 `DeleteTool` 组件弹确认框
+
+## 基础用法
+
+```vue
+<template>
+  <MessageTools
+    :on-action="handleAction"
+    @feedback="handleFeedback"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  // like / unlike 必须返回 Promise<string[]>，作为反馈表单的选项
+  const handleAction = async (tool: IToolBtn) => {
+    if (tool.id === 'like' || tool.id === 'unlike') {
+      return ['回答准确', '信息全面', '表达清晰', '解决了问题'];
+    }
+  };
+
+  // 用户在反馈表单点击"提交"后触发
+  const handleFeedback = (tool: IToolBtn, reasonList: string[], otherReason: string) => {
+    console.log('反馈:', tool.id, reasonList, otherReason);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 反馈交互流程
+
+点赞（`like`）和不满意（`unlike`）按钮的完整交互流程：
+
+```
+用户点击 like/unlike
+        │
+        ▼
+调用 onAction(tool)（显示 loading 状态）
+        │
+        ▼
+onAction 返回 string[]（反馈选项列表）
+        │
+        ▼
+弹出 UserFeedback 表单（显示选项）
+        │
+   ┌────┴────┐
+取消         提交
+  │           │
+关闭弹窗     emit('feedback', tool, reasonList, otherReason)
+             │
+             ▼
+          按钮切换为激活图标（activeLike / activeUnLike）
+          ↑ 再次点击同一按钮 → 取消激活并关闭弹窗（不触发 feedback）
+```
+
+**图标切换说明**：
+
+| 状态         | `like` 按钮图标          | `like` Tooltip   | `unlike` 按钮图标          | `unlike` Tooltip |
+| ------------ | ------------------------ | ---------------- | -------------------------- | ---------------- |
+| 未提交       | `like`（空心）           | 原始 description | `unlike`（空心）           | 原始 description |
+| 已提交点赞   | `activeLike`（实心填充） | 取消满意         | `unlike`（空心）           | 原始 description |
+| 已提交不满意 | `like`（空心）           | 原始 description | `activeUnLike`（实心填充） | 取消不满意       |
+
+> 激活态下 tooltip 内容自动切换为"取消满意"/"取消不满意"，用于提示用户再次点击可取消评价。
+
+## 默认工具列表
+
+### messageTools（左侧）
+
+```typescript
+const CONST_MESSAGE_TOOLS = [
+  { id: 'copy', name: '复制', description: '复制' },
+  { id: 'rebuild', name: '重新生成', description: '重新生成将清空下文内容' },
+  { id: 'share', name: '分享', description: '分享' },
+];
+```
+
+用户消息的内置列表（`CONST_USER_MESSAGE_TOOLS`，由 [UserMessage](/components/message/user-message) 使用）：
+
+```typescript
+const CONST_USER_MESSAGE_TOOLS = [
+  { id: 'copy', name: '复制', description: '复制' },
+  { id: 'edit', name: '编辑', description: '编辑' },
+  { id: 'delete', name: '删除', description: '删除' },
+];
+```
+
+> `cite`（引用）已从两份内置列表中移除，后续不再支持；`ToolBtn` 仍保留该 id 的图标，业务侧可自行把它作为自定义按钮传入。
+
+### updateTools（右侧）
+
+```typescript
+const CONST_UPDATE_TOOLS = [
+  { id: 'like', name: '点赞', description: '点赞' },
+  { id: 'unlike', name: '不满意', description: '不满意' },
+  { id: 'delete', name: '删除', description: '删除' },
+];
+```
+
+> **注意**：`delete` 在 `updateTools` 中**不弹反馈表单**，而是弹出确认删除弹窗（`DeleteTool`）。用户确认后才触发 `onAction`，取消则不触发。
+
+## 内置图标 ID
+
+`ToolBtn` 会根据 `tool.id` 自动匹配图标，支持以下 ID：
+
+| ID             | 图标说明                             |
+| -------------- | ------------------------------------ |
+| `copy`         | 复制                                 |
+| `cite`         | 引用（不再属于内置列表，可用于自定义按钮） |
+| `rebuild`      | 重新生成                             |
+| `share`        | 分享                                 |
+| `like`         | 点赞（空心）                         |
+| `unlike`       | 不满意（空心）                       |
+| `delete`       | 删除                                 |
+| `edit`         | 编辑                                 |
+| `activeLike`   | 点赞已激活（实心，由组件内部使用）   |
+| `activeUnLike` | 不满意已激活（实心，由组件内部使用） |
+
+> ID 不在列表中时，按钮显示 `tool.name` 文本。
+
+## 仅显示消息工具（不含反馈）
+
+将 `updateTools` 设为空数组可去掉右侧反馈按钮和分隔线：
+
+```vue
+<template>
+  <MessageTools
+    :message-tools="messageTools"
+    :update-tools="[]"
+    :on-action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  const messageTools: IToolBtn[] = [
+    { id: 'copy', name: '复制', description: '复制' },
+    { id: 'cite', name: '引用', description: '引用' },
+  ];
+
+  const handleAction = async (tool: IToolBtn) => {
+    console.log('操作:', tool.id);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 自定义工具列表
+
+`messageTools` 和 `updateTools` 均可完全替换：
+
+```vue
+<template>
+  <MessageTools
+    :message-tools="customMessageTools"
+    :update-tools="customUpdateTools"
+    :on-action="handleAction"
+    @feedback="handleFeedback"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  const customMessageTools: IToolBtn[] = [
+    { id: 'copy', name: '复制', description: '复制消息内容' },
+    { id: 'rebuild', name: '重新生成', description: '重新生成回答' },
+    { id: 'custom-action', name: '自定义', description: '自定义操作' }, // 无图标，显示文本
+  ];
+
+  // like / unlike 仍会触发反馈弹窗；delete 弹确认框，确认后触发 onAction
+  const customUpdateTools: IToolBtn[] = [
+    { id: 'like', name: '有帮助', description: '这个回答对我有帮助' },
+    { id: 'unlike', name: '没帮助', description: '这个回答没有帮助' },
+    { id: 'delete', name: '删除', description: '删除消息' },
+  ];
+
+  const handleAction = async (tool: IToolBtn) => {
+    if (tool.id === 'like' || tool.id === 'unlike') {
+      return ['回答准确', '信息全面', '表达清晰', '解决了问题'];
+    }
+    console.log('操作:', tool.id);
+  };
+
+  const handleFeedback = (tool: IToolBtn, reasonList: string[], otherReason: string) => {
+    console.log('反馈:', tool.id, reasonList, otherReason);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 两端插槽（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` 控制工具栏整体状态：
+
+| 值          | 效果                                                                   |
+| ----------- | ---------------------------------------------------------------------- |
+| `undefined` | 默认，按钮正常可点击，hover 有 tooltip                                 |
+| `disabled`  | 按钮显示但不可点击，tooltip 不显示，反馈弹窗无法打开                   |
+| `hidden`    | `MessageContainer` 检测到此值时不渲染 `MessageTools`（组件自身不处理） |
+
+> `hidden` 由 `MessageContainer` 在外部用 `v-if` 判断，`MessageTools` 本身不感知该值。
+
+**禁用状态**
+
+```vue
+<template>
+  <MessageTools
+    :message-tools-status="MessageToolsStatus.Disabled"
+    :on-action="handleAction"
+    @feedback="handleFeedback"
+  />
+</template>
+```
+
+## 自定义 Tippy 配置
+
+反馈弹窗的 `Tippy` 默认配置如下，可通过 `tippyOptions` 覆盖：
+
+```typescript
+// 内部默认值
+{
+  arrow: false,
+  interactive: true,
+  offset: [0, 6],
+  theme: 'ai-chat-box-light light',
+  trigger: 'click',
+  appendTo: () => document.body,
+}
+```
+
+```vue
+<template>
+  <MessageTools
+    :on-action="handleAction"
+    :tippy-options="tippyOptions"
+    @feedback="handleFeedback"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  const tippyOptions = {
+    placement: 'top', // 弹窗方向
+    offset: [0, 12], // 偏移量
+    appendTo: () => document.querySelector('#my-container') || document.body,
+  };
+
+  const handleAction = async (tool: IToolBtn) => {
+    if (tool.id === 'like' || tool.id === 'unlike') {
+      return ['回答准确', '信息全面'];
+    }
+  };
+  const handleFeedback = (tool: IToolBtn, reasonList: string[], otherReason: string) => {
+    console.log('反馈:', tool.id, reasonList);
+  };
+</script>
+```
+
+> **注意**：`content`、`theme`、`getReferenceClientRect`、`triggerTarget` 四个选项由组件内部管理，不可通过 `tippyOptions` 覆盖。
+
+## 在 MessageContainer 中的使用
+
+`MessageContainer` 在每个 Assistant 消息组底部自动渲染 `MessageTools`，无需手动引入：
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :message-status="messageStatus"
+    :message-tools-status="messageToolsStatus"
+    :on-agent-action="handleAgentAction"
+    :on-agent-feedback="handleAgentFeedback"
+    @stop-streaming="handleStopStreaming"
+  />
+</template>
+
+<script setup lang="ts">
+  import { computed, ref } from 'vue';
+  import { MessageContainer, MessageStatus, MessageToolsStatus, type Message, type IToolBtn } from '@blueking/chat-x';
+
+  const messageStatus = ref(MessageStatus.Complete);
+
+  // 流式输出时禁用工具栏，避免误操作
+  const messageToolsStatus = computed(() =>
+    messageStatus.value === MessageStatus.Streaming ? MessageToolsStatus.Disabled : undefined,
+  );
+
+  // copy 操作由 MessageContainer 内部自动处理（无需在此实现）
+  const handleAgentAction = async (tool: IToolBtn, messages: Message[]) => {
+    if (tool.id === 'like' || tool.id === 'unlike') {
+      return ['回答准确', '信息全面', '表达清晰'];
+    }
+  };
+
+  const handleAgentFeedback = (tool: IToolBtn, messages: Message[], reasonList: string[], otherReason: string) => {
+    console.log('反馈提交:', tool.id, reasonList, otherReason);
+  };
+
+  const handleStopStreaming = () => {
+    messageStatus.value = MessageStatus.Stop;
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名             | 类型                                                                                                     | 默认值                | 说明                                                                                                                                 |
+| ------------------ | -------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| messageTools       | `IToolBtn[]`                                                                                             | `CONST_MESSAGE_TOOLS` | 左侧工具列表                                                                                                                         |
+| updateTools        | `IToolBtn[]`                                                                                             | `CONST_UPDATE_TOOLS`  | 右侧工具列表（`like`/`unlike` 弹反馈表单，`delete` 弹确认框，其他直接触发 `onAction`）                                               |
+| messageToolsStatus | `MessageToolsStatus`                                                                                     | —                     | 工具栏状态：`disabled` 禁用按钮和弹窗                                                                                                |
+| onAction           | `(tool: IToolBtn, content?: UserMessage['content'], docSchema?: TagSchema) => Promise<string[] \| void>` | —                     | 工具操作回调；`like`/`unlike` 需返回 `string[]` 作为反馈选项；`delete` 确认后触发；`content`、`docSchema` 为可选参数，供上层扩展使用 |
+| tippyOptions       | `AITippyProps`                                                                                           | —                     | 覆盖反馈弹窗和删除确认弹窗的默认配置；可覆盖 `placement` 等                                                                          |
+
+### Events
+
+| 事件名   | 参数                                                          | 触发时机                                   |
+| -------- | ------------------------------------------------------------- | ------------------------------------------ |
+| feedback | `(tool: IToolBtn, reasonList: string[], otherReason: string)` | 用户在反馈表单点击"提交"后触发（not 取消） |
+
+### Slots
+
+| 插槽名  | 作用域参数 | 说明                                             |
+| ------- | ---------- | ------------------------------------------------ |
+| prepend | —          | 工具图标左侧的附加内容，如用户消息的时间         |
+| append  | —          | 工具图标右侧的附加内容，如 AI 消息组的时间       |
+
+## 类型定义
+
+```typescript
+import { MessageToolsStatus, type IToolBtn } from '@blueking/chat-x';
+import type { Component, VNode } from 'vue';
+
+interface IToolBtn {
+  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 {
+  Disabled = 'disabled', // 禁用：按钮显示但不可点击，弹窗不打开
+  Hidden = 'hidden', // 隐藏：由 MessageContainer 外部 v-if 控制，组件本身不处理
+}
+```
+
+## 关联组件
+
+- [ToolBtn](/components/feedback/tool-btn) — 单项工具按钮
+- [UserFeedback](/components/feedback/user-feedback) — 点赞/踩反馈面板
+- [DeleteTool](/components/feedback/delete-tool) — 删除二次确认
+- [MessageTime](/components/feedback/message-time) — 两端插槽内的消息时间

package/skills/blueking-chat-x/references/components/model-selector.md

@@ -0,0 +1,157 @@
+# ModelSelector 模型选择器
+
+> 能力域：输入交互 ｜ 导入：`import { ModelSelector } from '@blueking/chat-x'` ｜ since 1.0.0
+
+聊天输入区的模型下拉选择器，支持搜索过滤、能力标签与键盘导航。 源码位置：src/components/chat-input/model-selector/model-selector.vue。
+
+**关联**：chat-input（传入 models 后在发送按钮左侧默认渲染）、input-attachment（通过 before-send 插槽与发送按钮成组布局）
+
+---
+
+# 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?: Component | string; // 图标 URL 或 Vue 组件，由 ResourceIcon 渲染
+  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`）。
+5. 图标由 [ResourceIcon](/components/helper/resource-icon) 渲染（`type="model"`）：支持图片 URL 或 Vue 组件，URL 加载失败自动回退到内置兜底图标；未提供 `icon` 时不渲染图标位。
+
+## 关联组件
+
+- [ChatInput](/components/input/chat-input)：传入 `models` 后默认在发送按钮左侧渲染本组件，也可通过 `#model-selector` 插槽完全自定义。
+- [ChatContainer](/components/setup/chat-container)：透传 `models` 与 `v-model:selected-model`，并向上 emit `modelChange`。
+- [ResourceIcon](/components/helper/resource-icon)：触发器与选项的图标渲染。

package/skills/blueking-chat-x/references/components/preview-toolbar.md

@@ -0,0 +1,42 @@
+# PreviewToolbar 图片预览工具栏
+
+> 能力域：媒体文件 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+图片预览的缩放、旋转、下载等工具按钮。 源码位置：src/components/image-preview/preview-toolbar.vue。
+
+---
+
+# PreviewToolbar 图片预览工具栏
+
+> **能力域**：媒体文件
+
+## 源码事实
+
+- **源码位置**：`src/components/image-preview/preview-toolbar.vue`
+- **能力说明**：图片预览的缩放、旋转、下载等工具按钮。
+
+## API 摘要
+
+### Props
+
+- `{ activeIndex: number; currentImageInfo?: null | { resolution?: string; width?: number }; isMultiple: boolean; showInfo: boolean; total: number; }`
+
+### Emits
+
+- `{ (e: 'zoomIn'): void; (e: 'zoomOut'): void; (e: 'rotate'): void; (e: 'reset'): void; (e: 'download'): void; }`
+
+### Slots
+
+- `extra`
+
+### Expose
+
+- 无。
+
+## 组件依赖
+
+- 无组件依赖或仅依赖基础库。
+
+## 使用建议
+
+- 优先通过上层组合组件使用；直接使用前请确认 props 数据结构来自对应类型定义。