@blueking/chat-x 0.0.5 → 0.0.7

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

@@ -0,0 +1,202 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ShortcutBtn 渲染单个快捷指令入口，封装图标解析与「按钮 / 下拉菜单项」两种布局，并暴露根元素供父级测量。 由 ShortcutBtns、AiSelection、ChatInput 内部复用；含 components 的快捷指令可无默认图标。 通过 click 事件传出当前 Shortcut，append 槽常用于关闭按钮。
+
+### 关联组件
+- **shortcut-btns** — 快捷指令横向列表中作为单项渲染
+- **ai-selection** — 划词浮窗内展示快捷操作按钮或溢出菜单项
+- **chat-input** — 已选快捷指令在输入框底部以单按钮展示
+
+---
+<!-- FULL DOC -->
+
+# ShortcutBtn 快捷指令按钮
+
+> **层级**：原子组件 · **功能域**：输入交互
+
+单个快捷指令的渲染单元，封装图标选择逻辑和两种布局模式（按钮 / 菜单项）。
+
+被 `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 class="ai-common-icon ai-shortcut-btn-icon" :src="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>`                     | 同时有 `.ai-common-icon .ai-shortcut-btn-icon` |
+| `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](./shortcut-btns.md) — 快捷指令列表容器
+- [AiSelection](../molecular/ai-selection.md) — 划词浮窗内使用
+- [ChatInput](../molecular/chat-input.md) — 已选快捷指令展示

package/dist/mcp/generated/docs/shortcut-btns.md

@@ -0,0 +1,264 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ShortcutBtns 横向展示快捷指令按钮组，按容器宽度动态计算可见数量，溢出收入「更多」下拉。 默认由 ChatInput 嵌入附件槽；选中含 components 的指令后需配合 ShortcutRender 展示表单。 通过 selectShortcut 等与外层同步当前快捷指令。
+
+### 关联组件
+- **shortcut-btn** — 列表中每一项由 ShortcutBtn 渲染
+- **chat-input** — 默认嵌入输入框底部附件区
+- **shortcut-render** — 表单类快捷指令选中后的表单渲染
+
+---
+<!-- FULL DOC -->
+
+# ShortcutBtns 快捷指令按钮组
+
+> **层级**：原子组件 · **功能域**：输入交互
+
+快捷指令按钮列表，内置**响应式溢出收起**：根据容器实际宽度动态计算可见数量，超出部分自动收入"更多"下拉菜单。
+
+通常由 `ChatInput` 内部使用，一般不需要手动引入。
+
+## 组件结构
+
+```
+div.shortcut-btns（flex，gap: 4px，width: 100%，min-width: 168px，max-width: 1000px，overflow: hidden）
+  │
+  ├── ShortcutBtn.shortcut-btns-item × N（每个快捷指令）
+  │     height: 24px，padding: 0 6px，white-space: nowrap，background: #fff，border-radius: 4px
+  │     溢出时追加 .shortcut-btns-item-hidden（position: absolute; visibility: hidden; pointer-events: none; opacity: 0）
+  │       注意：隐藏项仍在 DOM 中，仅通过 CSS 不可见，offsetWidth 仍可读
+  │
+  └── [hiddenShortcuts.length > 0] Tippy（trigger="manual"，append-to="body"，interactive）
+        │  offset=[0,6]，z-index=SHORTCUT_MENU_Z_INDEX，theme="ai-chat-box-light light"
+        ├── ShortcutBtn.shortcut-btns-more（触发按钮）
+        │     MoreAgentIcon（rotate(90deg)） + "更多"
+        └── #content: div.shortcut-menu
+              ShortcutBtn（mode="menu"） × 隐藏数量
+```
+
+## 响应式溢出机制（useObserverVisibleList）
+
+组件使用 `ResizeObserver` 监听容器宽度变化，自动计算可见按钮列表：
+
+```
+calculateVisibleMenuItems 执行逻辑：
+  1. 遍历 shortcuts（按顺序）
+  2. 每项计算：neededWidth = totalWidth + itemWidth + gap（非首项才加 gap）
+  3. 判断：neededWidth + gap + moreButtonWidth ≤ containerWidth
+       → true：加入 visibleItems，更新 totalWidth
+       → false：break（后续项全部进入"更多"菜单）
+  4. 触发时机：ResizeObserver 回调 / itemRefs 变化 / moreItemRef 变化
+```
+
+- `shortcuts` prop 通过 `computed(() => props.shortcuts)` 包装为 `ComputedRef` 传入 `useObserverVisibleList`，确保 items 变化时计算逻辑能访问到最新数据
+- `shortcuts` prop 更新时（深度 watch），`itemRefs` 重置为同等长度的 null 数组，再等待下一帧重新计算
+- 隐藏项 = `shortcuts.filter(s => !visibleItems.includes(s))`，保持原始顺序
+- `ResizeObserver` 在 `onScopeDispose` 时断开，无内存泄漏
+
+## 基础用法
+
+```vue
+<template>
+  <ShortcutBtns
+    :shortcuts="shortcuts"
+    @select-shortcut="handleSelectShortcut"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ShortcutBtns } from '@blueking/chat-x';
+  import type { Shortcut } from '@blueking/chat-x';
+
+  const shortcuts: Shortcut[] = [
+    { id: 'ask', name: '问问小鲸' },
+    { id: 'translate', name: '翻译' },
+    { id: 'summarize', name: '总结' },
+    { id: 'explain', name: '解释代码' },
+    { id: 'code-review', name: '代码审查' },
+  ];
+
+  const handleSelectShortcut = (shortcut: Shortcut) => {
+    console.log('选择了:', shortcut.name);
+  };
+</script>
+```
+
+## 带描述的快捷指令
+
+`description` 字段由 `ShortcutRender` 表单弹窗使用（悬浮提示或说明文字），本组件不直接渲染：
+
+```vue
+<template>
+  <ShortcutBtns
+    :shortcuts="shortcuts"
+    @select-shortcut="handleSelectShortcut"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ShortcutBtns } from '@blueking/chat-x';
+  import type { Shortcut } from '@blueking/chat-x';
+
+  const shortcuts: Shortcut[] = [
+    { id: 'translate', name: '翻译', description: '将文本翻译成指定语言' },
+    { id: 'summarize', name: '总结', description: '自动总结长文本的核心要点' },
+    { id: 'explain', name: '解释', description: '解释代码或概念' },
+  ];
+</script>
+```
+
+## 带表单的快捷指令
+
+配置 `components` 后，`@select-shortcut` 事件仍正常触发，**表单弹窗逻辑需由父组件配合 `ShortcutRender` 实现**：
+
+```vue
+<template>
+  <ShortcutBtns
+    :shortcuts="shortcuts"
+    @select-shortcut="handleSelectShortcut"
+  />
+  <ShortcutRender
+    v-if="activeShortcut"
+    :shortcut="activeShortcut"
+    @submit="handleFormSubmit"
+    @cancel="activeShortcut = null"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ShortcutBtns, ShortcutRender } from '@blueking/chat-x';
+  import type { Shortcut } from '@blueking/chat-x';
+
+  const activeShortcut = ref<Shortcut | null>(null);
+
+  const shortcuts: Shortcut[] = [
+    {
+      id: 'translate',
+      name: '翻译',
+      description: '将文本翻译成指定语言',
+      components: [
+        {
+          type: 'select',
+          key: 'targetLang',
+          name: '目标语言',
+          props: {
+            options: [
+              { label: '英文', value: 'en' },
+              { label: '中文', value: 'zh' },
+            ],
+          },
+        },
+        { type: 'textarea', key: 'content', name: '翻译内容', fillBack: true },
+      ],
+    },
+    {
+      id: 'code-gen',
+      name: '代码生成',
+      components: [
+        { type: 'input', key: 'language', name: '编程语言' },
+        { type: 'textarea', key: 'description', name: '功能描述', fillBack: true },
+      ],
+    },
+  ];
+
+  const handleSelectShortcut = (shortcut: Shortcut) => {
+    if (shortcut.components?.length) {
+      activeShortcut.value = shortcut; // 打开表单弹窗
+    } else {
+      sendMessage(shortcut); // 直接发送
+    }
+  };
+</script>
+```
+
+## 响应式溢出（"更多"菜单）
+
+当按钮数量超出容器可用宽度时，自动显示"更多"按钮，点击展开下拉菜单：
+
+> 该 Demo 容器较窄时会自动触发溢出收起效果。`manyShortcuts` 共 12 项，超出容器宽度的按钮进入"更多"下拉菜单。
+
+## API
+
+### Props
+
+| 属性名    | 类型         | 必填 | 说明                                                                |
+| --------- | ------------ | ---- | ------------------------------------------------------------------- |
+| shortcuts | `Shortcut[]` | 是   | 快捷指令列表；`v-for` 使用 `shortcut.key \|\| shortcut.id` 作为 key |
+
+### Events
+
+| 事件名          | 参数                   | 说明                                                                         |
+| --------------- | ---------------------- | ---------------------------------------------------------------------------- |
+| select-shortcut | `(shortcut: Shortcut)` | 点击任意快捷指令（含"更多"菜单中的项）时触发；从"更多"菜单选择后菜单自动关闭 |
+
+## 类型定义
+
+```typescript
+interface Shortcut {
+  id: string;
+  name: string;
+  key?: string; // 自定义 v-for key，优先于 id
+  description?: string;
+  icon?: string | VNode | ((h: typeof h) => Component | VNode);
+  components?: ShortcutComponent[];
+  formModel?: Record<string, unknown>;
+}
+
+type ShortcutComponent =
+  | InputShortcutComponent // type: 'input'
+  | TextareaShortcutComponent // type: 'textarea'
+  | NumberShortcutComponent // type: 'number'
+  | SelectShortcutComponent // type: 'select'
+  | CheckboxGroupShortcutComponent // type: 'checkboxGroup'
+  | RadioGroupShortcutComponent // type: 'radioGroup'
+  | SwitcherShortcutComponent // type: 'switcher'
+  | TextShortcutComponent; // type: 'text'（纯文本展示）
+
+interface BaseShortcutComponent<T> {
+  type: T;
+  key: string; // 表单字段 key，对应 formModel 中的属性名
+  name?: string; // 表单项 label
+  fillBack?: boolean; // true 时，该字段值在提交后回填至聊天输入框
+  props?: Record<string, any>; // 传给底层 bkui-vue 组件的 props
+  formItemProps?: Record<string, any>; // 传给 bkui-vue Form.Item 的 props
+}
+```
+
+### 表单组件类型
+
+| type 值         | 底层组件                  | 说明                                    |
+| --------------- | ------------------------- | --------------------------------------- |
+| `input`         | bkui-vue Input            | 单行文本输入                            |
+| `textarea`      | bkui-vue Input (textarea) | 多行文本输入                            |
+| `number`        | bkui-vue Input (number)   | 数字输入                                |
+| `select`        | bkui-vue Select           | 下拉选择，通过 `props.options` 配置选项 |
+| `checkboxGroup` | bkui-vue Checkbox.Group   | 多选框组                                |
+| `radioGroup`    | bkui-vue Radio.Group      | 单选框组                                |
+| `switcher`      | bkui-vue Switcher         | 开关                                    |
+| `text`          | 纯文本                    | 仅展示说明文字，不收集值                |
+
+## 样式说明
+
+| 类名                         | 样式                                                                       | 说明                                               |
+| ---------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------- |
+| `.shortcut-btns`             | `width: 100%; min-width: 168px; max-width: 1000px; overflow: hidden`       | 容器，宽度撑满父元素，超出 1000px 截断             |
+| `.shortcut-btns-item`        | `height: 24px; padding: 0 6px; background: #fff; border-radius: 4px`       | 每个快捷指令按钮的外层包装 class                   |
+| `.shortcut-btns-item-hidden` | `position: absolute; visibility: hidden; pointer-events: none; opacity: 0` | 溢出按钮的隐藏态；仍在 DOM 中以便 offsetWidth 计算 |
+| `.shortcut-btns-more`        | `flex-shrink: 0; padding: 0 6px`                                           | "更多"按钮，`MoreAgentIcon` 旋转 90°               |
+| `.shortcut-menu`             | `@include menu.ai-common-menu-style`                                       | 下拉菜单容器样式                                   |
+
+## 注意事项
+
+1. **`key` 字段优先于 `id`**：`v-for` 使用 `shortcut.key || shortcut.id`，当多个指令 `id` 相同但代表不同实例时，可通过 `key` 字段区分
+2. **溢出项不可交互**：`.shortcut-btns-item-hidden` 通过 `pointer-events: none` 屏蔽点击，不会误触发事件
+3. **"更多"菜单 Teleport 至 body**：Tippy 使用 `append-to="body"`，避免被父容器的 `overflow: hidden` 裁剪
+4. **容器宽度限制**：`min-width: 168px` 和 `max-width: 1000px` 来自 `$chat-input-min-width` / `$chat-input-max-width` 变量，与输入框宽度保持一致
+5. **表单流程在外部**：`ShortcutBtns` 只负责显示和触发事件，`components` 的表单弹窗逻辑需配合 `ShortcutRender` 实现（`ChatInput` 已内置此流程）
+
+## 关联组件
+
+- [ShortcutBtn](./shortcut-btn.md) — 列表项原子组件
+- [ChatInput](../molecular/chat-input.md) — 默认嵌入输入框底部
+- [ShortcutRender](../molecular/shortcut-render.md) — 表单类快捷指令的表单渲染