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

package/skills/blueking-chat-x/references/components/scroll-btn.md

@@ -0,0 +1,159 @@
+# ScrollBtn 滚动按钮
+
+> 能力域：工具与反馈 ｜ 导入：`import { ScrollBtn } from '@blueking/chat-x'` ｜ since 1.0.0
+
+停止生成或返回底部等滚动/状态按钮。 源码位置：src/components/ai-buttons/scroll-btn/scroll-btn.vue。
+
+**关联**：message-container（消息列表底部固定区挂载滚动与停止按钮）
+
+---
+
+# ScrollBtn 滚动按钮
+## 源码事实
+
+- **源码位置**：`src/components/ai-buttons/scroll-btn/scroll-btn.vue`
+- **能力域**：工具与反馈
+- **能力说明**：停止生成或返回底部等滚动/状态按钮。
+
+> **能力域**：工具与反馈
+
+聊天容器底部浮动操作按钮的外壳组件，提供统一的胶囊样式（圆角 26px、高 24px、阴影），内容完全由插槽定制。
+
+由 `MessageContainer` 内部管理"停止生成"和"返回底部"两个按钮的显示逻辑，通常不需要手动引入。
+
+## 组件结构
+
+```
+div.ai-scroll-btn（flex，gap: 4px，width: fit-content，min-width: 84px，height: 24px）
+  .is-loading / .is-disabled → cursor: not-allowed，opacity: 0.65
+  border: 1px solid #dcdee5，border-radius: 26px
+  box-shadow: 0 -2px 6px 0 #0000001a
+  hover → border: #c4c6cc，box-shadow 加深，cursor: pointer
+  │
+  ├── Loading（loading=true 时显示旋转加载图标）
+  ├── <slot name="icon">（loading=false 时显示，无默认内容）
+  │     子图标自动继承 .ai-common-icon 样式：14×14px，font-size: 14px
+  │
+  └── <slot name="title">（默认内容：{{ title }}，XSS 安全）
+        传入 title slot 时完全替换 title prop 的文本
+```
+
+> **`loading` / `disabled` prop**：`loading` 为 `true` 时显示旋转加载图标替代 icon slot，且点击无效；`disabled` 为 `true` 时点击同样无效。两者均添加 `not-allowed` 光标和 `0.65` 透明度。
+>
+> **`@click` 事件**：通过内部 `handleClick` 处理，`loading` 或 `disabled` 时不触发。
+
+## 基础用法：返回底部
+
+```vue
+<template>
+  <ScrollBtn
+    title="返回底部"
+    @click="toScrollBottom"
+  >
+    <template #icon>
+      <ArrowDownIcon />
+    </template>
+  </ScrollBtn>
+</template>
+
+<script setup lang="ts">
+  import { ScrollBtn } from '@blueking/chat-x';
+  import { ArrowDownIcon } from '@blueking/chat-x';
+
+  const toScrollBottom = () => {
+    /* 滚动逻辑 */
+  };
+</script>
+```
+
+## 停止生成
+
+```vue
+<template>
+  <ScrollBtn
+    title="停止生成"
+    @click="stopStreaming"
+  >
+    <template #icon>
+      <CloseCircleIcon />
+    </template>
+  </ScrollBtn>
+</template>
+```
+
+## 仅图标（不传 title）
+
+不传 `title` prop 时，`title` slot 渲染空文本，按钮收缩至 `min-width: 84px`：
+
+## 自定义 title slot
+
+传入 `#title` 插槽时，完全覆盖 `title` prop 的文本渲染：
+
+```vue
+<template>
+  <ScrollBtn
+    title="此文本被覆盖"
+    @click="handleClick"
+  >
+    <template #icon>
+      <ArrowDownIcon />
+    </template>
+    <template #title>
+      <span style="color: #3a84ff; font-weight: 600;">新消息 ↓</span>
+    </template>
+  </ScrollBtn>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型      | 必填 | 说明                                                                      |
+| -------- | --------- | ---- | ------------------------------------------------------------------------- |
+| title    | `string`  | —    | 按钮文本；被 `#title` 插槽覆盖时无效；XSS 安全（文本插值）                |
+| loading  | `boolean` | —    | 加载状态；为 `true` 时显示旋转 Loading 图标替代 icon slot，点击不触发事件 |
+| disabled | `boolean` | —    | 禁用状态；为 `true` 时点击不触发事件                                      |
+
+### Events
+
+| 事件名 | 参数                  | 说明                                             |
+| ------ | --------------------- | ------------------------------------------------ |
+| click  | `(event: MouseEvent)` | 点击按钮时触发；`loading` 或 `disabled` 时不触发 |
+
+### Slots
+
+| 插槽名 | 说明                                                                      |
+| ------ | ------------------------------------------------------------------------- |
+| icon   | 图标区域，无默认内容；放置 `@blueking/chat-x` 图标时自动应用 14×14px 样式 |
+| title  | 文本区域，默认渲染 `title` prop；传入后**完全替换** prop 文本             |
+
+## 在 MessageContainer 中的使用
+
+`ScrollBtn` 由 `MessageContainer` 内置，根据状态自动控制显隐，无需手动管理：
+
+```html
+<!-- 停止生成：仅在流式输出时显示 -->
+<ScrollBtn
+  v-show="messageStatus === MessageStatus.Streaming"
+  :title="t('停止生成')"
+  @click="$emit('stopStreaming')"
+>
+  <template #icon><CloseCircleIcon /></template>
+</ScrollBtn>
+
+<!-- 返回底部：距底部超过 100px 且不在底部时显示 -->
+<ScrollBtn
+  v-show="!isScrollBottom && scrollBottomHeight > 100"
+  :title="t('返回底部')"
+  @click="toScrollBottom"
+>
+  <template #icon><ArrowDownIcon /></template>
+</ScrollBtn>
+```
+
+两个按钮都渲染在 `div.ai-message-fixed-bottom` 容器内，由父布局定位到消息列表底部中央。
+
+## 关联组件
+
+- [MessageContainer](/components/setup/message-container) — 底部固定区集成

package/skills/blueking-chat-x/references/components/selection-footer.md

@@ -0,0 +1,78 @@
+# SelectionFooter 多选操作栏
+
+> 能力域：输入交互 ｜ 导入：`import { SelectionFooter } from '@blueking/chat-x'` ｜ since 1.0.0
+
+消息多选/分享模式下的底部操作栏。 源码位置：src/components/selection-footer/selection-footer.vue。
+
+**关联**：chat-container（多选/分享模式由容器渲染底部栏）、message-container（与消息列表勾选状态联动）
+
+---
+
+# SelectionFooter 选择操作栏
+## 源码事实
+
+- **源码位置**：`src/components/selection-footer/selection-footer.vue`
+- **能力域**：输入交互
+- **能力说明**：消息多选/分享模式下的底部操作栏。
+
+> **能力域**：输入交互
+
+消息多选模式下的底部操作栏，提供全选、取消和确认操作。由 `ChatContainer` 在分享模式下自动渲染，通常不需要单独使用。
+
+## 基础用法
+
+```vue
+<template>
+  <SelectionFooter
+    :is-all-selected="isAllSelected"
+    :selected-count="selectedCount"
+    :loading="false"
+    @toggle-all="handleToggleAll"
+    @cancel="handleCancel"
+    @confirm="handleConfirm"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { SelectionFooter } from '@blueking/chat-x';
+
+  const isAllSelected = ref(false);
+  const selectedCount = ref(0);
+
+  const handleToggleAll = (checked: boolean) => {
+    isAllSelected.value = checked;
+  };
+  const handleCancel = () => {
+    console.log('取消');
+  };
+  const handleConfirm = () => {
+    console.log('确认');
+  };
+</script>
+```
+
+**渲染效果**
+
+## API
+
+### Props
+
+| 属性名        | 类型      | 必填 | 默认值  | 说明                          |
+| ------------- | --------- | ---- | ------- | ----------------------------- |
+| isAllSelected | `boolean` | ✓    | —       | 是否全选                      |
+| selectedCount | `number`  | ✓    | —       | 已选数量，为 0 时确认按钮禁用 |
+| loading       | `boolean` | —    | `false` | 确认按钮加载状态              |
+
+### Events
+
+| 事件名     | 参数                 | 说明         |
+| ---------- | -------------------- | ------------ |
+| toggle-all | `(checked: boolean)` | 切换全选状态 |
+| cancel     | —                    | 点击取消按钮 |
+| confirm    | —                    | 点击确认按钮 |
+
+## 关联组件
+
+- [ChatContainer](/components/setup/chat-container) — 分享模式挂载
+- [MessageContainer](/components/setup/message-container) — 多选与消息列表

package/skills/blueking-chat-x/references/components/selection-question.md

@@ -0,0 +1,88 @@
+# SelectionQuestion 选择问题占位
+
+> 能力域：辅助能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。 源码位置：src/components/ai-questions/selection-question.vue。
+
+**关联**：user-question-card（选择类问题交互请使用实际可渲染的问题卡片组件）、user-question-option（单个选项行由实际问题组件渲染）、interrupt-message（HITL 中断消息由 InterruptMessage 分发到具体问题组件）
+
+---
+
+# SelectionQuestion 选择问题占位
+
+> **能力域**：辅助能力
+
+`SelectionQuestion` 当前只是保留在源码目录中的空文件，占位路径为 `src/components/ai-questions/selection-question.vue`。它没有模板、脚本、样式、props、emits、slots 或任何选择交互能力。
+
+本文档保留该条目，是为了明确它不是当前可用的问题选择组件，避免业务误接入。
+
+## 源码事实
+
+- **源码位置**：`src/components/ai-questions/selection-question.vue`
+- **文件大小**：`0` 字节
+- **能力说明**：源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。
+
+## 当前状态
+
+| 项目     | 状态 |
+| -------- | ---- |
+| 模板     | 无   |
+| 脚本逻辑 | 无   |
+| 样式     | 无   |
+| Props    | 无   |
+| Emits    | 无   |
+| Slots    | 无   |
+| Expose   | 无   |
+
+## 不可用示例
+
+下面的写法不会产生选择题 UI，也不会发出确认事件：
+
+```vue
+<template>
+  <!-- 不建议使用：当前组件为空文件 -->
+  <SelectionQuestion />
+</template>
+```
+
+## 推荐替代
+
+选择类用户问题请走中断消息链路，由已实现的组件负责展示选项和处理确认：
+
+```vue
+<template>
+  <UserQuestionCard
+    :content="content"
+    @confirm="handleConfirm"
+  />
+</template>
+```
+
+相关文档：
+
+- [UserQuestionCard](../agent/user-question-card.md) — 用户问题中断交互面板。
+- [UserQuestionOption](../agent/user-question-option.md) — 用户问题选项行。
+- [InterruptMessage](../agent/interrupt-message.md) — 中断消息分发入口。
+
+## API
+
+### Props
+
+- 无。
+
+### Emits
+
+- 无。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 使用建议
+
+- 不建议在业务中使用该组件。
+- 如果后续补齐实现，需要同步更新本文档的示例、选择交互事件、API 与关联组件。

package/skills/blueking-chat-x/references/components/shortcut-btn.md

@@ -0,0 +1,204 @@
+# ShortcutBtn 快捷指令按钮
+
+> 能力域：输入交互 ｜ 导入：`import { ShortcutBtn } from '@blueking/chat-x'` ｜ since 1.0.0
+
+单个快捷指令按钮，支持默认/append 插槽和 expose focus。 源码位置：src/components/ai-shortcut/shortcut-btn/shortcut-btn.vue。
+
+**关联**：shortcut-btns（快捷指令横向列表中作为单项渲染）、ai-selection（划词浮窗内展示快捷操作按钮或溢出菜单项）、chat-input（已选快捷指令在输入框底部以单按钮展示）
+
+---
+
+# ShortcutBtn 快捷指令按钮
+## 源码事实
+
+- **源码位置**：`src/components/ai-shortcut/shortcut-btn/shortcut-btn.vue`
+- **能力域**：输入交互
+- **能力说明**：单个快捷指令按钮，支持默认/append 插槽和 expose focus。
+
+> **能力域**：输入交互
+
+单个快捷指令的渲染单元，封装图标选择逻辑和两种布局模式（按钮 / 菜单项）。
+
+被 `ShortcutBtns`（快捷指令栏）、`AiSelection`（划词浮窗）和 `ChatInput`（已选指令展示）内部使用，通常不需要手动引入。
+
+## 组件结构
+
+```
+button.ai-shortcut-btn（flex，gap: 4px，height: 28px，padding: 0 4px，white-space: nowrap）
+  border: none，border-radius: 4px，background: transparent
+  transition: background-color 0.2s
+  mode="menu" → 追加 .is-menu-mode（height: 32px，padding: 0 12px，width: 100%，justify-content: flex-start）
+  │
+  ├── <slot name="default">（覆盖后图标+名称全部替换）
+  │     ├── [shortcut.icon 为字符串 && 以 'http' 开头]
+  │     │     加载成功：<img … />；加载失败：回退 AgentIcon.ai-shortcut-btn-icon
+  │     ├── [shortcut.icon 为字符串 && 不以 'http' 开头]
+  │     │     <span :class="icon" />（CSS 图标类名，无其他 class）
+  │     ├── [shortcut.icon 为函数或组件]
+  │     │     <component :is="typeof icon==='function' ? icon(h) : icon" class="ai-shortcut-btn-icon" />
+  │     ├── [shortcut 存在，无 icon，components 为空/未设置] → AgentIcon.ai-shortcut-btn-icon
+  │     ├── [shortcut 存在，无 icon，components 有内容]      → 无图标
+  │     └── {{ shortcut?.name }}（XSS 安全，文本插值）
+  │
+  └── <slot name="append" />（渲染在名称之后，常用于关闭按钮）
+
+defineExpose: { get $el() { return el.value } }（懒 getter，返回 button 元素引用）
+```
+
+> **`hover` cursor 说明**：CSS 中 `:hover` 先写 `cursor: pointer` 再写 `cursor: default`，后者覆盖前者，实际 hover 时显示默认指针。仅 `append` 槽内的 `.ai-close-icon` 恢复 `cursor: pointer`。
+
+## 图标渲染规则
+
+| `shortcut.icon` 类型                  | 渲染结果                    | 额外说明                                                         |
+| ------------------------------------- | --------------------------- | ---------------------------------------------------------------- |
+| 未设置（且 `components` 为空/未设置） | `AgentIcon`（默认图标）     | `components: []` 与不传效果相同                                  |
+| 未设置（且 `components` 有内容）      | 无图标                      | 表单类快捷指令                                                   |
+| `string`，以 `'http'` 开头            | `<img>`，失败时 `AgentIcon` | `.ai-common-icon .ai-shortcut-btn-icon`；`@error` 后回退默认图标 |
+| `string`，不以 `'http'` 开头          | `<span :class="icon">`      | 视为 CSS 图标类名，无其他 class                                  |
+| 函数 `(h) => Component/VNode`         | `<component :is="icon(h)">` | 有 `.ai-shortcut-btn-icon`                                       |
+| 组件对象                              | `<component :is="icon">`    | 有 `.ai-shortcut-btn-icon`                                       |
+
+## 基础用法
+
+```vue
+<template>
+  <ShortcutBtn
+    :shortcut="shortcut"
+    @click="handleClick"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ShortcutBtn } from '@blueking/chat-x';
+  import type { Shortcut } from '@blueking/chat-x';
+
+  const shortcut: Shortcut = { id: 'ask-whale', name: '问问小鲸' };
+
+  const handleClick = (shortcut?: Shortcut) => {
+    console.log('选择了:', shortcut?.name);
+  };
+</script>
+```
+
+> 从左到右：无 `icon`（默认 AgentIcon）、`components: []`（同样显示 AgentIcon）、有 `components`（无图标）。
+
+## 图标类型对比
+
+```vue
+<template>
+  <!-- URL 图片图标 -->
+  <ShortcutBtn :shortcut="{ id: '1', name: '图片图标', icon: 'https://…/icon.png' }" />
+
+  <!-- CSS 类名图标（字体图标） -->
+  <ShortcutBtn :shortcut="{ id: '2', name: 'CSS 类图标', icon: 'bk-icon icon-star-shape' }" />
+
+  <!-- 函数/渲染函数图标 -->
+  <ShortcutBtn :shortcut="{ id: '3', name: '函数图标', icon: h => h('span', {}, '🚀') }" />
+</template>
+```
+
+## 菜单模式（mode="menu"）
+
+`mode="menu"` 时切换为 `is-menu-mode` 布局：左对齐、`width: 100%`、高 32px、padding `0 12px`：
+
+```vue
+<template>
+  <div class="shortcut-menu">
+    <ShortcutBtn
+      v-for="item in shortcuts"
+      :key="item.id"
+      mode="menu"
+      :shortcut="item"
+      @click="handleClick"
+    />
+  </div>
+</template>
+```
+
+## append 插槽：添加关闭按钮
+
+`#append` 渲染在名称之后，`@click.stop` 可阻止冒泡到 `@click`（父 ChatInput 使用场景）：
+
+```vue
+<template>
+  <ShortcutBtn
+    :shortcut="shortcut"
+    @click="handleSelect"
+  >
+    <template #append>
+      <CloseIcon @click.stop="handleRemove" />
+    </template>
+  </ShortcutBtn>
+</template>
+```
+
+## default 插槽：完全自定义内容
+
+`default` 插槽覆盖**全部**默认内容（图标 + 名称），`shortcut` prop 仅传递给 `@click` 事件：
+
+```vue
+<template>
+  <ShortcutBtn
+    :shortcut="shortcut"
+    @click="handleClick"
+  >
+    <MoreAgentIcon />
+    <span>更多</span>
+  </ShortcutBtn>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型              | 必填 | 说明                                                         |
+| -------- | ----------------- | ---- | ------------------------------------------------------------ |
+| shortcut | `Shortcut`        | —    | 快捷指令配置；缺省时按钮无内容，`click` 事件传递 `undefined` |
+| mode     | `'btn' \| 'menu'` | —    | 布局模式；缺省为 `btn`（水平居中），`menu` 切换为列表项布局  |
+
+### Events
+
+| 事件名 | 参数                    | 说明                                                                 |
+| ------ | ----------------------- | -------------------------------------------------------------------- |
+| click  | `(shortcut?: Shortcut)` | 点击按钮时触发，传递当前 `shortcut` prop（无 prop 则为 `undefined`） |
+
+### Slots
+
+| 插槽名  | 说明                                                                 |
+| ------- | -------------------------------------------------------------------- |
+| default | 覆盖全部默认渲染（图标 + 名称）；`shortcut` prop 仍用于 `click` 事件 |
+| append  | 追加在名称之后；常用于关闭/删除图标，建议配合 `@click.stop` 阻止冒泡 |
+
+### Expose
+
+| 属性名 | 类型                  | 说明                                                                      |
+| ------ | --------------------- | ------------------------------------------------------------------------- |
+| `$el`  | `HTMLElement \| null` | 懒 getter，返回根 `<button>` 元素引用；供 `ShortcutBtns` 计算可见性时使用 |
+
+## 类型定义
+
+```typescript
+interface Shortcut {
+  id: string;
+  name: string;
+  description?: string;
+  icon?: string | Component | ((h: typeof h) => Component | VNode);
+  components?: ShortcutComponent[]; // 有内容时不显示默认 AgentIcon
+  formModel?: Record<string, unknown>;
+}
+```
+
+## 在各组件中的使用场景
+
+| 使用方         | 模式          | 特殊用法                                                                                     |
+| -------------- | ------------- | -------------------------------------------------------------------------------------------- |
+| `ShortcutBtns` | btn           | 可见项正常渲染；溢出项隐藏（CSS `visibility: hidden`），放入下拉菜单以 `mode="menu"` 展示    |
+| `AiSelection`  | btn / menu    | 最多显示 `maxShortcutCount` 个按钮，超出时以 `#default` 插槽显示"更多"，下拉用 `mode="menu"` |
+| `ChatInput`    | btn（已选态） | 使用 `#append` 插槽放置 `CloseIcon`，点击关闭删除已选快捷指令                                |
+
+## 关联组件
+
+- [ShortcutBtns](/components/input/shortcut-btns) — 快捷指令列表容器
+- [AiSelection](/components/input/ai-selection) — 划词浮窗内使用
+- [ChatInput](/components/input/chat-input) — 已选快捷指令展示