npm - @blueking/chat-x - Versions diffs - 0.0.51-beta.5 → 0.0.52-dev.1 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (198) hide show

package/skills/blueking-chat-x/references/components/ai-selection.md ADDED Viewed

@@ -0,0 +1,439 @@
+# AiSelection 划词选择
+> 能力域：输入交互 ｜ 导入：`import { AiSelection } from '@blueking/chat-x'` ｜ since 1.0.0
+监听选中文本并展示快捷操作浮窗。 源码位置：src/components/ai-selection/ai-selection.vue。
+**关联**：shortcut-btn（弹窗内快捷指令按钮/菜单项由该基础组件渲染）、chat-input（划词结果常回填或触发与输入框联动的快捷指令）
+---
+# AiSelection AI 划词选择弹窗
+## 源码事实
+- **源码位置**：`src/components/ai-selection/ai-selection.vue`
+- **能力域**：输入交互
+- **能力说明**：监听选中文本并展示快捷操作浮窗。
+> **能力域**：输入交互
+AI 划词选择组件，监听用户在页面中的文本选区，在选区附近弹出快捷操作菜单。支持自定义快捷指令列表、数量限制、垂直偏移以及完全自定义插槽内容。
+> **注意**：`AiSelection` 通过 `document.addEventListener` 监听全局事件（`selectionchange`、`mouseup`、`mousedown`、`scroll`），**同一页面中只应挂载一个实例**，避免多实例同时响应导致事件重复和弹窗叠加。
+## 工作原理
+```
+用户选中文本
+   ↓  mouseup（200ms 防抖）/ selectionchange（300ms 防抖）
+获取选区文本 & 坐标 → 计算弹窗位置
+   ↓
+通过 <Teleport to="body"> 将弹窗渲染到 <body> 末尾
+   ↓
+用户点击快捷指令 → 触发 selectShortcut 事件 → 关闭弹窗
+```
+弹窗渲染在 `<body>` 顶层，不受父级 `overflow: hidden` / `z-index` 影响，定位坐标基于视口（`position: fixed`）。
+## 弹窗关闭时机
+| 触发条件           | 说明                             |
+| ------------------ | -------------------------------- |
+| 点击弹窗外部区域   | `mousedown` 事件，弹窗外任意位置 |
+| 滚动包含选区的容器 | `scroll` 事件捕获阶段            |
+| 窗口大小改变       | `window.resize`                  |
+| 窗口失去焦点       | `window.blur`                    |
+| 点击快捷指令       | 触发后立即关闭并清除选区         |
+## 基础用法
+不传 `shortcuts` 时，使用内置默认快捷指令"问问小鲸"（`id: 'ai-chat'`）：
+```vue
+<template>
+  <AiSelection v-model:visible="selectionVisible" />
+</template>
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { AiSelection } from '@blueking/chat-x';
+  const selectionVisible = ref(false);
+</script>
+```
+**渲染效果**（选中下方文字后弹出快捷操作菜单）
+## 自定义快捷指令
+通过 `shortcuts` 属性传入自定义快捷指令列表：
+```vue
+<template>
+  <AiSelection
+    v-model:visible="selectionVisible"
+    :shortcuts="shortcuts"
+    @select-shortcut="handleSelectShortcut"
+    @selection-change="handleSelectionChange"
+  />
+</template>
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { AiSelection, type Shortcut } from '@blueking/chat-x';
+  const selectionVisible = ref(false);
+  const shortcuts: Shortcut[] = [
+    { id: 'ai-chat', name: '问问小鲸' },
+    { id: 'translate', name: '翻译' },
+    { id: 'explain', name: '解释' },
+  ];
+  const handleSelectShortcut = (shortcut: Shortcut, selectedText: string) => {
+    console.log('触发指令:', shortcut.name, '选中文本:', selectedText);
+  };
+  const handleSelectionChange = (text: string) => {
+    console.log('选区变化:', text);
+  };
+</script>
+```
+**渲染效果**（选中文字后弹出 3 个快捷操作按钮）
+## 快捷指令数量限制
+当快捷指令数量超过 `maxShortcutCount`（默认 `3`）时，多余的指令会收起到「更多」菜单（点击 `›` 箭头展开）。
+### `maxShortcutCount = 3`（默认）
+6 个指令中前 3 个直接展示，其余 3 个收起：
+```vue
+<template>
+  <AiSelection
+    v-model:visible="selectionVisible"
+    :shortcuts="shortcuts"
+  />
+</template>
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { AiSelection, type Shortcut } from '@blueking/chat-x';
+  const selectionVisible = ref(false);
+  const shortcuts: Shortcut[] = [
+    { id: 'ai-chat', name: '问问小鲸' },
+    { id: 'translate', name: '翻译' },
+    { id: 'explain', name: '解释' },
+    { id: 'summarize', name: '总结' },
+    { id: 'improve', name: '改进' },
+    { id: 'code', name: '生成代码' },
+  ];
+</script>
+```
+**渲染效果**（展示 3 个，其余 3 个收起到「更多」菜单）
+### `maxShortcutCount = 5`
+前 5 个直接展示，仅最后 1 个收起：
+```vue
+<AiSelection v-model:visible="selectionVisible" :shortcuts="shortcuts" :max-shortcut-count="5" />
+```
+**渲染效果**（展示 5 个，仅「生成代码」收起）
+## 带图标的快捷指令
+`icon` 属性支持三种形式：
+| 类型                              | 说明            | 示例                             |
+| --------------------------------- | --------------- | -------------------------------- |
+| `string`（emoji）                 | 直接渲染文本    | `'🌐'`                           |
+| `string`（HTTP URL）              | 渲染为 `<img>`  | `'https://example.com/icon.svg'` |
+| `VNode \| (c: typeof h) => VNode` | 渲染为 Vue 组件 | `ThinkingIcon`（内置图标组件）   |
+```vue
+<script setup lang="ts">
+  import { h } from 'vue';
+  import { AiSelection, type Shortcut } from '@blueking/chat-x';
+  const shortcuts: Shortcut[] = [
+    {
+      id: 'ai-chat',
+      name: '问问小鲸',
+      // VNode 渲染函数
+      icon: c => c('span', { style: 'font-size: 14px;' }, '🐳'),
+    },
+    {
+      id: 'translate',
+      name: '翻译',
+      icon: '🌐', // Emoji 字符串
+    },
+    {
+      id: 'search',
+      name: '搜索',
+      icon: 'https://example.com/search-icon.svg', // URL（渲染为 img）
+    },
+  ];
+</script>
+```
+## 事件回调
+`selectShortcut` 在用户点击快捷指令后触发，携带指令对象和选中文本；`selectionChange` 在选区文字内容变化时触发：
+```vue
+<template>
+  <div>
+    <p>选中文字后点击快捷指令，观察下方回调信息。</p>
+    <AiSelection
+      v-model:visible="selectionVisible"
+      :shortcuts="shortcuts"
+      @select-shortcut="handleSelectShortcut"
+      @selection-change="handleSelectionChange"
+    />
+    <div
+      v-if="selectedInfo.shortcut"
+      class="callback-info"
+    >
+      <p>触发指令：{{ selectedInfo.shortcut }}</p>
+      <p>选中文本：{{ selectedInfo.text }}</p>
+    </div>
+  </div>
+</template>
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { AiSelection, type Shortcut } from '@blueking/chat-x';
+  const selectionVisible = ref(false);
+  const selectedInfo = ref({ shortcut: '', text: '' });
+  const shortcuts: Shortcut[] = [
+    { id: 'ai-chat', name: '问问小鲸' },
+    { id: 'translate', name: '翻译' },
+    { id: 'explain', name: '解释' },
+  ];
+  const handleSelectShortcut = (shortcut: Shortcut, selectedText: string) => {
+    selectedInfo.value = { shortcut: shortcut.name, text: selectedText };
+  };
+  const handleSelectionChange = (text: string) => {
+    console.log('选区变化:', text);
+  };
+</script>
+```
+**渲染效果**（点击快捷指令后下方显示回调信息）
+## 自定义垂直偏移
+`offset` 控制弹窗与选区之间的垂直距离（单位 px），默认 `10`。弹窗优先显示在选区**上方**，空间不足时自动显示在**下方**：
+```vue
+<!-- 间距 20px -->
+<AiSelection v-model:visible="selectionVisible" :offset="20" />
+<!-- 紧贴选区（间距 0） -->
+<AiSelection v-model:visible="selectionVisible" :offset="0" />
+```
+## 自定义插槽
+默认插槽替换整个弹窗内容区，插槽参数 `shortcuts` 为**完整**快捷指令列表（未经 `maxShortcutCount` 截断）：
+```vue
+<template>
+  <AiSelection
+    v-model:visible="selectionVisible"
+    :shortcuts="shortcuts"
+  >
+    <template #default="{ shortcuts }">
+      <div class="my-menu">
+        <button
+          v-for="shortcut in shortcuts"
+          :key="shortcut.id"
+          @click="handleClick(shortcut)"
+        >
+          {{ shortcut.name }}
+        </button>
+      </div>
+    </template>
+  </AiSelection>
+</template>
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { AiSelection, type Shortcut } from '@blueking/chat-x';
+  const selectionVisible = ref(false);
+  const shortcuts: Shortcut[] = [
+    { id: 'ai-chat', name: '问问小鲸' },
+    { id: 'translate', name: '翻译' },
+  ];
+  const handleClick = (shortcut: Shortcut) => {
+    const text = window.getSelection()?.toString() || '';
+    console.log(shortcut.name, text);
+  };
+</script>
+```
+> **注意**：使用默认插槽后，`maxShortcutCount` 不再生效，「更多」菜单也不会出现，需要自行处理超出逻辑。
+## 排除区域
+通过 `excludeSelectors` 指定 CSS 选择器列表，当选区位于这些选择器匹配的元素内部时，弹窗不会弹出。适用于代码块、表单输入等不需要划词弹窗的区域：
+```vue
+<template>
+  <AiSelection
+    v-model:visible="selectionVisible"
+    :exclude-selectors="['.code-block', '.no-selection']"
+  />
+  <div class="code-block">这里选中文字不会弹出操作菜单</div>
+  <div class="no-selection">这里也不会弹出</div>
+  <p>这里选中文字正常弹出操作菜单</p>
+</template>
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { AiSelection } from '@blueking/chat-x';
+  const selectionVisible = ref(false);
+</script>
+```
+## Input / Textarea 支持
+组件对 `<input>` 和 `<textarea>` 中的选区进行了特殊处理：原生 Range 在这两类元素中无法获取准确坐标，组件会降级使用**输入框自身的 `getBoundingClientRect()`** 作为弹窗位置参考。
+## 与 ChatBot 联动
+选中文本后触发快捷指令，自动将选中内容作为上下文发送到聊天窗口：
+```vue
+<template>
+  <div class="page">
+    <article>文章内容...</article>
+    <AiSelection
+      v-model:visible="selectionVisible"
+      :shortcuts="shortcuts"
+      @select-shortcut="handleSelectShortcut"
+    />
+    <ChatBot ref="chatBotRef" />
+  </div>
+</template>
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { AiSelection, ChatBot, type Shortcut } from '@blueking/chat-x';
+  const selectionVisible = ref(false);
+  const chatBotRef = ref();
+  const shortcuts: Shortcut[] = [
+    { id: 'ai-chat', name: '问问小鲸' },
+    { id: 'translate', name: '翻译' },
+    { id: 'explain', name: '解释' },
+  ];
+  const handleSelectShortcut = (shortcut: Shortcut, selectedText: string) => {
+    const prompts: Record<string, string> = {
+      translate: `请翻译以下内容：\n${selectedText}`,
+      explain: `请解释以下内容：\n${selectedText}`,
+    };
+    chatBotRef.value?.sendMessage(prompts[shortcut.id] ?? selectedText);
+  };
+</script>
+```
+<!-- 全页唯一的 AiSelection 实例，通过各演示区的 mousedown 切换当前配置 -->
+<AiSelectionComp
+v-model:visible="selectionVisible"
+:shortcuts="currentConfig.shortcuts"
+:max-shortcut-count="currentConfig.maxShortcutCount"
+@select-shortcut="handleSelectShortcut"
+/>
+## API
+### Props
+| 属性名           | 类型         | 默认值              | 必填 | 说明                                                    |
+| ---------------- | ------------ | ------------------- | ---- | ------------------------------------------------------- |
+| visible          | `boolean`    | -                   | ✅   | 控制弹窗显示，必须使用 `v-model:visible`                |
+| shortcuts        | `Shortcut[]` | `DEFAULT_SHORTCUTS` | -    | 快捷指令列表，默认为内置「问问小鲸」                    |
+| maxShortcutCount | `number`     | `3`                 | -    | 直接展示的最大指令数，超出收起到「更多」菜单            |
+| offset           | `number`     | `10`                | -    | 弹窗与选区的垂直间距（px）                              |
+| excludeSelectors | `string[]`   | `[]`                | -    | 排除的 CSS 选择器数组，选区在这些选择器内部时不显示弹窗 |
+### Events
+| 事件名          | 参数                                 | 说明                                    |
+| --------------- | ------------------------------------ | --------------------------------------- |
+| selectShortcut  | `(shortcut: Shortcut, text: string)` | 点击快捷指令时触发，`text` 为选中的文本 |
+| selectionChange | `(text: string)`                     | 选区文本内容发生变化时触发              |
+### Slots
+| 插槽名  | 参数                        | 说明                                           |
+| ------- | --------------------------- | ---------------------------------------------- |
+| default | `{ shortcuts: Shortcut[] }` | 自定义弹窗内容，`shortcuts` 为完整快捷指令列表 |
+## 定位逻辑
+| 方向     | 规则                                                                                 |
+| -------- | ------------------------------------------------------------------------------------ |
+| 水平方向 | 弹窗居中对齐选区，超出视口左/右边界时自动贴边（保留 8px 间距）                       |
+| 垂直方向 | 优先显示在选区**上方**，上方空间不足时显示在**下方**；两侧均不足时选择空间较大的一侧 |
+## 默认快捷指令
+```typescript
+const DEFAULT_SHORTCUTS: Shortcut[] = [{ id: 'ai-chat', name: '问问小鲸' }];
+```
+## Shadow DOM 支持
+组件会递归查找当前 `document.activeElement` 下的 Shadow DOM，兼容 Web Components 场景。若 Shadow DOM 中存在有效文本选区，弹窗同样会正常弹出并定位。
+## 类型定义
+```typescript
+import { type Component, type VNode, h } from 'vue';
+interface Shortcut {
+  id: string;
+  name: string;
+  key?: string;
+  icon?: ((c: typeof h) => Component | VNode) | string | VNode;
+  components?: ShortcutComponent[];
+  // ... 其余字段参见 ShortcutRender 文档
+}
+```
+## 使用场景
+- **文章阅读划词**：选中内容后弹出「问问小鲸」「翻译」「解释」等快捷入口
+- **代码解释**：在代码区块中选中代码片段，触发「解释代码」「优化建议」等操作
+- **文本处理**：对选中内容进行翻译、总结、改写等 AI 增强处理
+- **与 ChatBot 联动**：选中文本后将内容作为上下文自动填入聊天输入框
+## 关联组件
+- [ShortcutBtn](/components/input/shortcut-btn) — 弹窗内快捷指令按钮单元
+- [ChatInput](/components/input/chat-input) — 选区文本常回填到聊天输入框

package/skills/blueking-chat-x/references/components/ai-slash-input.md ADDED Viewed

@@ -0,0 +1,102 @@
+# AiSlashInput 富文本命令输入
+> 能力域：输入交互 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+ChatInput 内部富文本编辑区，基于 edix 编辑器渲染「文本 + 资源标签」文档。 自身不渲染菜单，只把触发方式与过滤关键字通过 menuChange 抛给上层，并暴露插入 / 替换 / 关闭菜单等命令。 源码位置：src/components/chat-input/ai-slash-input/ai-slash-input.vue。
+**关联**：chat-input（上层输入区，持有菜单状态并调用本组件的 expose 方法）、input-menu-panel（由 menuChange 驱动的菜单面板，选中后回调插入方法）、mention-tag（文档中的 tag 节点由 MentionTag 渲染）
+---
+# AiSlashInput 富文本命令输入
+> **能力域**：输入交互
+## 源码事实
+- **源码位置**：`src/components/chat-input/ai-slash-input/ai-slash-input.vue`
+- **能力说明**：基于 [edix](/edix/) 的 `contenteditable` 编辑区，文档结构为 `TagSchema`（二维数组：行 → 节点，节点为 `text` 或 `tag`）。
+- **职责边界**：只管「编辑 + 触发态识别 + 插入」，**不渲染菜单**。菜单的数据、分组、显隐都在 [ChatInput](/components/input/chat-input) 与 [InputMenuPanel](/components/input/input-menu-panel) 中。
+## 触发状态机
+触发状态由 `use-menu-trigger.ts` 维护，对外统一为 `{ trigger, keyword }`：
+| 触发方式             | 唤起时机                | 过滤关键字来源                             | 选中时消费的字符      |
+| -------------------- | ----------------------- | ------------------------------------------ | --------------------- |
+| `/` `@` `\`（字符）  | `keydown` 命中触发字符  | 触发符 → 光标之间的非空白文本              | 关键字 + 触发符       |
+| `plus`               | 上层调用 `openPlusMenu` | 唤起瞬间光标位置 → 当前光标之间的文本      | 仅关键字              |
+- 内容或光标变化后延迟 16ms 重算触发态（等 DOM 应用本次输入），上下文失效（如光标移到触发符之前）时自动关闭。
+- `plus` 唤起时若编辑器还没有文本节点（空输入框），关键字保持为空。
+- 每次 `trigger` / `keyword` 变化都会 emit `menuChange`。
+## 文档与标签
+标签是 edix 的 void 节点，识别依据是 `contenteditable="false"` 且带 `data-tag-type` 属性；节点数据全部落在 DOM 属性上，因此文档可以脱离 `menuSources` 独立还原（消息回显与 hover 气泡都依赖这点）：
+| 节点数据      | 来源                          | DOM 属性              |
+| ------------- | ----------------------------- | --------------------- |
+| `label`       | `item.name`                   | `data-tag-label`      |
+| `value`       | `item.id`                     | `data-tag-value`      |
+| `type`        | `item.type`                   | `data-tag-type`       |
+| `icon`        | `item.icon`（仅字符串 URL）   | `data-tag-icon`       |
+| `description` | `item.description`            | `data-tag-description` |
+序列化为纯文本时，`skill` 输出 `/<value>`，其余类型输出 `@<label>`（见 `constants.ts` 的 `tagSchemaToMessageString`）。
+## 与 modelValue 的同步
+`modelValue` 支持 `string` 与 `TagSchema` 两种形态：传字符串时经 `stringToDoc` 转成文档。当 `modelValue` 由外部异步更新（历史会话回填、父组件重置、编辑态回填）且与编辑器当前内容不一致时，组件通过 `GetDocSnapshot` 读取快照并与 `docToString(modelValue)` 比对，必要时执行 `ReplaceAll` 同步，避免内外状态脱节。
+## 粘贴与换行
+- 粘贴内容中包含文件时阻止默认行为并 emit `upload`，交由上层走上传流程；纯文本粘贴保持编辑器默认行为。
+- `Enter` 阻止编辑器默认换行（发送与否由上层判断），`Shift + Enter` 正常换行。
+- 编辑区默认保持 4 行高度，避免输入后 placeholder 消失导致高度抖动；父级触达 `max-height` 后由本组件内部滚动。
+## API
+### Props
+| 属性名      | 类型                  | 默认值                     | 必填 | 说明                       |
+| ----------- | --------------------- | -------------------------- | ---- | -------------------------- |
+| modelValue  | `string \| TagSchema` | -                          | ✅   | 编辑器文档                 |
+| placeholder | `string`              | `请输入内容` / `Please enter content` | - | 占位文案，经 `aria-placeholder` 渲染，支持 `\n` 多行 |
+### Emits
+| 事件名            | 参数                                                    | 触发时机                       |
+| ----------------- | ------------------------------------------------------- | ------------------------------ |
+| update:modelValue | `(value: TagSchema)`                                    | 编辑器内容变化                 |
+| keydown           | `(event: KeyboardEvent & KeyboardPayload)`              | 编辑器按键（上层据此判断发送） |
+| upload            | `(files: File[])`                                       | 粘贴内容中含文件               |
+| menuChange        | `(payload: { keyword: string; trigger: MenuTrigger \| null })` | 触发方式或过滤关键字变化 |
+### Expose
+| 方法名               | 类型                                     | 说明                                                             |
+| -------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
+| insertMenuItem       | `(item: IInputMenuItem) => void`         | 消费「触发符 + 关键字」后在光标处插入标签并补一个空格             |
+| appendMention        | `(item: IInputMenuItem) => void`         | 在文档末尾追加标签（位置由文档算出，不读光标，供外部无焦点时调用） |
+| replaceAll           | `(value: string) => void`                | 整体替换文档内容（Prompt 选中走此路径）                          |
+| consumeTriggerText   | `() => [number, number]`                 | 仅删除「触发符 + 关键字」，返回删除后的 `[line, column]`         |
+| closeMenu            | `() => void`                             | 关闭触发态                                                       |
+| cleanup              | `() => void`                             | 清空文档并关闭触发态（发送后调用）                               |
+| focus                | `() => void`                             | 聚焦编辑器并把光标置于末尾                                       |
+| openPlusMenu         | `() => void`                             | 唤起 `plus` 聚合菜单；光标已在编辑器内时保持原位                 |
+::: tip 为什么 appendMention 不读光标
+外部调用（如文件产物面板点「引用」）时编辑器通常没有焦点，而 DOM 选区与编辑器内部选区是异步同步的，依赖光标会把标签插到错误位置，因此位置直接由文档末尾算出。
+:::
+## 使用建议
+直接使用本组件需要自行实现菜单与插入调度，通常应通过 [ChatInput](/components/input/chat-input) 使用。若确需单独接入，最小闭环是：监听 `menuChange` 决定菜单显隐与数据 → 用户选中后调用 `insertMenuItem` / `replaceAll` → 发送后调用 `cleanup`。
+## 关联组件
+- [ChatInput](/components/input/chat-input) — 上层输入区
+- [InputMenuPanel](/components/input/input-menu-panel) — 菜单面板与分组逻辑
+- [MentionTag](/components/rendering/mention-tag) — 标签渲染
+- [Edix 编辑器引擎](/edix/) — 文档模型与命令机制