@blueking/chat-x 0.0.5 → 0.0.6

package/dist/mcp/generated/docs/use-animation-text.md

@@ -0,0 +1,198 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useAnimationText 接收 MaybeRef<string> 与可选 AnimationConfig（fadeDuration、easing），返回 chunks 与 animationStyle。 监听文本变化：前缀追加则增量拆分为新 chunk 并触发动画，否则重置为单 chunk，适合流式输出逐段淡入。 全局样式已含 ai-markdown-fade-in。AnimationText 原子组件内部封装同一逻辑。
+
+### 关联组件
+- **animation-text** — 封装 chunks 与样式渲染
+- **markdown-content** — 流式 Markdown 文本展示场景可组合使用
+
+---
+<!-- FULL DOC -->
+
+# useAnimationText
+
+> **分类**：composable
+
+文本淡入动画的组合式函数。将响应式文本按**增量**拆分为独立 chunk，每个新增 chunk 对应一次淡入动画，适用于 AI 流式输出的逐段渐显效果。
+
+## 工作原理
+
+每当 `text` 发生变化时，composable 通过比较新旧文本决定如何更新 chunks：
+
+| 变化情况                            | 处理方式                  |
+| ----------------------------------- | ------------------------- |
+| 新文本以旧文本为前缀（追加）        | 将增量部分追加为新 chunk  |
+| 新文本与旧文本完全不同（替换/重置） | chunks 重置为 `[newText]` |
+| 文本未变化                          | 无操作                    |
+
+每个 chunk 对应一个独立的 DOM 节点，节点加入 DOM 时自动触发 `ai-markdown-fade-in` 淡入动画。
+
+> `@keyframes ai-markdown-fade-in` 已内置于 `@blueking/chat-x` 全局样式，**无需手动定义**。
+
+## 基础用法
+
+将 `Ref<string>` 传入 composable，配合 `v-for` + `:style` 渲染各 chunk。
+
+```vue
+<template>
+  <div>
+    <span
+      v-for="(chunk, index) in chunks"
+      :key="index"
+      :style="animationStyle"
+      >{{ chunk }}</span
+    >
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useAnimationText } from '@blueking/chat-x';
+
+  const text = ref('');
+  const { chunks, animationStyle } = useAnimationText(text);
+
+  // 模拟流式追加
+  async function startStreaming() {
+    const fullText = '这是一段模拟 AI 流式输出的文本内容...';
+    for (const char of fullText) {
+      text.value += char;
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+  }
+
+  startStreaming();
+</script>
+```
+
+**渲染效果**
+
+## 自定义动画配置
+
+通过 `options` 调整淡入动画的持续时间和缓动函数。
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useAnimationText } from '@blueking/chat-x';
+
+  const text = ref('');
+  const { chunks, animationStyle } = useAnimationText(text, {
+    fadeDuration: 600, // 淡入持续时间，默认 200ms
+    easing: 'ease-out', // CSS 缓动函数，默认 'ease-in-out'
+  });
+</script>
+```
+
+**渲染效果**（fadeDuration=600ms）
+
+## 文本重置行为
+
+当 `text` 被完全替换（新值不以旧值为前缀）时，chunks 会重置为单一片段，之前积累的 chunks 清空。这适用于多轮对话中切换消息的场景。
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useAnimationText } from '@blueking/chat-x';
+
+  const text = ref('');
+  const { chunks, animationStyle } = useAnimationText(text);
+
+  async function nextMessage(newContent: string) {
+    // 直接替换整个 text，chunks 自动重置
+    text.value = '';
+    for (const char of newContent) {
+      text.value += char;
+      await new Promise(r => setTimeout(r, 50));
+    }
+  }
+</script>
+```
+
+**渲染效果**（两条消息依次播放，第二条时 chunks 重置）
+
+## 使用 AnimationText 组件
+
+如无需定制渲染逻辑，可直接使用封装好的 `AnimationText` 组件，内部已集成 `useAnimationText`：
+
+```vue
+<template>
+  <AnimationText :text="text" />
+</template>
+
+<script setup lang="ts">
+  import { AnimationText } from '@blueking/chat-x';
+</script>
+```
+
+> 详见 [AnimationText 组件文档](/components/atomic/animation-text)。
+
+## API
+
+### 函数签名
+
+```typescript
+function useAnimationText(
+  text: MaybeRef<string>,
+  options?: AnimationConfig,
+): {
+  chunks: Ref<string[]>;
+  animationStyle: ComputedRef<CSSProperties>;
+};
+```
+
+### 参数
+
+| 参数      | 类型               | 必填 | 说明                                      |
+| --------- | ------------------ | ---- | ----------------------------------------- |
+| `text`    | `MaybeRef<string>` | 是   | 响应式文本，传入 `Ref<string>` 可追踪变化 |
+| `options` | `AnimationConfig`  | 否   | 动画配置                                  |
+
+### AnimationConfig
+
+| 属性           | 类型     | 默认值          | 说明                   |
+| -------------- | -------- | --------------- | ---------------------- |
+| `fadeDuration` | `number` | `200`           | 淡入动画持续时间（ms） |
+| `easing`       | `string` | `'ease-in-out'` | CSS 缓动函数           |
+
+### 返回值
+
+| 属性             | 类型                         | 说明                                       |
+| ---------------- | ---------------------------- | ------------------------------------------ |
+| `chunks`         | `Ref<string[]>`              | 拆分后的文本片段数组，每个片段对应一次动画 |
+| `animationStyle` | `ComputedRef<CSSProperties>` | 所有 chunk 共用的动画样式对象              |
+
+## 类型定义
+
+```typescript
+import type { MaybeRef, Ref, ComputedRef, CSSProperties } from 'vue';
+
+interface AnimationConfig {
+  fadeDuration?: number;
+  easing?: string;
+}
+
+function useAnimationText(
+  text: MaybeRef<string>,
+  options?: AnimationConfig,
+): {
+  chunks: Ref<string[]>;
+  animationStyle: ComputedRef<CSSProperties>;
+};
+```
+
+## 注意事项
+
+1. **在组件 `setup` 中通过 `watch(text, ...)` 直接监听 Ref**：composable 内部使用 `watch(() => text, ...)` 的 getter 形式，当 `text` 是 `Ref` 时，getter 每次返回同一个 Ref 对象，Vue 判断为"值未变化"，**watch 不会触发**。在自定义 setup 中如需直接响应文本变化，请用 `watch(text, handler)` 而非 `watch(() => text, handler)`。
+
+2. **`animationStyle` 为所有 chunk 共享的同一个对象**：动画效果来自每个 chunk 对应的 DOM 节点被创建时触发，而非样式本身的差异。
+
+3. **内置 CSS 关键帧**：引入 `@blueking/chat-x` 的全局样式后，`@keyframes ai-markdown-fade-in` 自动可用，无需手动定义。
+
+4. **性能**：长时间流式输出会积累大量 chunk 节点，动画完成后（`forwards`）这些节点保持 `opacity: 1`，对性能影响可接受；如有需要可在流式结束后将 `text` 合并为单次赋值以归并 chunk
+
+## 关联组件
+
+- [AnimationText](../components/atomic/animation-text.md) — 默认封装组件
+- [MarkdownContent](../components/atomic/markdown-content.md) — 富文本流式展示场景。

package/dist/mcp/generated/docs/use-clipboard.md

@@ -0,0 +1,206 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useClipboard 返回 { copy }，copy(text) 将字符串写入剪贴板，返回 Promise<void>。 优先使用 navigator.clipboard.writeText，失败或不支持时降级为隐藏 textarea + execCommand('copy')。 成功/失败均通过 bkui-vue Message 提示，调用方无需处理结果。CodeContent、MessageContainer、UserMessage 的复制能力内部使用。
+
+### 关联组件
+- **code-content** — 复制代码块时取 innerText 后调用 copy
+- **message-container** — AI 消息复制工具回调
+- **user-message** — 用户消息复制工具回调
+
+---
+<!-- FULL DOC -->
+
+# useClipboard 剪贴板
+
+> **分类**：composable
+
+复制文本到剪贴板的组合式函数。内置两级降级策略，并自动通过 bkui-vue `Message` 提示复制结果，调用方无需关心成功/失败处理。
+
+## 执行流程
+
+```
+copy(text)
+  │
+  ├── isClipboardApiSupported（模块加载时判断一次）
+  │     = typeof navigator !== 'undefined' && 'clipboard' in navigator
+  │
+  ├── true → navigator.clipboard.writeText(text)
+  │           ├── 成功 → success = true
+  │           └── 失败（权限拒绝等）→ legacyCopy(text)
+  │
+  └── false → legacyCopy(text)
+              （创建隐藏 textarea，document.execCommand('copy')，finally 清理 DOM）
+  │
+  └── Message({ message: t('复制成功/失败'), theme: 'success/error' })
+```
+
+> **注意**：`copy` 返回 `Promise<void>`，调用方无法获取成功/失败结果；通知由内部自动弹出，不可关闭或自定义。
+
+## 基础用法
+
+```vue
+<template>
+  <button @click="handleCopy">复制文本</button>
+</template>
+
+<script setup lang="ts">
+  import { useClipboard } from '@blueking/chat-x';
+
+  const { copy } = useClipboard();
+
+  const handleCopy = () => {
+    copy('Hello, World!');
+    // 自动弹出"复制成功/失败"提示，无需额外处理
+  };
+</script>
+```
+
+## 复制代码块内容
+
+`CodeContent` 组件内部的实际用法，取 DOM 元素的 `innerText` 避免 HTML 实体：
+
+```vue
+<template>
+  <div class="code-block">
+    <pre ref="codeRef"><code>{{ code }}</code></pre>
+    <button @click="handleCopyCode">复制代码</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { useTemplateRef } from 'vue';
+  import { useClipboard } from '@blueking/chat-x';
+
+  const codeRef = useTemplateRef<HTMLElement>('codeRef');
+  const { copy } = useClipboard();
+
+  // 使用 innerText 获取渲染后的纯文本，而非原始 token.content
+  const handleCopyCode = () => {
+    copy(codeRef.value?.innerText ?? '');
+  };
+</script>
+```
+
+## 复制消息内容
+
+`MessageContainer` 和 `UserMessage` 内部的实际用法：
+
+```vue
+<script setup lang="ts">
+  import { useClipboard } from '@blueking/chat-x';
+
+  const { copy } = useClipboard();
+
+  // 在 onAction 工具回调中调用
+  const onAction = tool => {
+    if (tool.id === 'copy') {
+      copy(props.content ?? '');
+    }
+  };
+</script>
+```
+
+## API
+
+### 返回值
+
+| 属性名 | 类型                              | 说明                                                 |
+| ------ | --------------------------------- | ---------------------------------------------------- |
+| copy   | `(text: string) => Promise<void>` | 复制文本；内部自动弹出结果提示，调用方无需处理返回值 |
+
+### copy(text)
+
+```typescript
+const copy: (text: string) => Promise<void>;
+```
+
+**参数：**
+
+- `text: string`：要复制的文本内容
+
+**内部行为：**
+
+| 步骤         | 说明                                                                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------------------- |
+| 1. 能力检测  | 模块导入时执行一次：`typeof navigator !== 'undefined' && 'clipboard' in navigator`                             |
+| 2a. 现代路径 | `navigator.clipboard.writeText(text)`，捕获异常后降级到步骤 2b                                                 |
+| 2b. 降级路径 | 创建隐藏 `textarea`（`position: fixed; left: -9999px; opacity: 0`），`execCommand('copy')`，`finally` 清理 DOM |
+| 3. 通知      | 始终调用 `Message({ message: t('复制成功/失败'), theme: 'success/error' })`                                    |
+
+## 实现源码
+
+```typescript
+import { Message } from 'bkui-vue';
+import { t } from '../lang/lang';
+
+// 模块加载时检测一次，SSR 安全
+const isClipboardApiSupported = typeof navigator !== 'undefined' && 'clipboard' in navigator;
+
+const legacyCopy = (text: string): boolean => {
+  const textarea = document.createElement('textarea');
+  textarea.value = text;
+  textarea.style.cssText = 'position:fixed;left:-9999px;top:-9999px;opacity:0';
+  document.body.appendChild(textarea);
+  textarea.focus();
+  textarea.select();
+  try {
+    return document.execCommand('copy');
+  } catch {
+    return false;
+  } finally {
+    document.body.removeChild(textarea); // 无论成败都清理 DOM
+  }
+};
+
+export const useClipboard = () => {
+  const copy = async (text: string) => {
+    let success = false;
+    if (isClipboardApiSupported) {
+      try {
+        await navigator.clipboard.writeText(text);
+        success = true;
+      } catch {
+        success = legacyCopy(text); // Clipboard API 失败时降级
+      }
+    } else {
+      success = legacyCopy(text);
+    }
+    Message({
+      message: success ? t('复制成功') : t('复制失败'),
+      theme: success ? 'success' : 'error',
+    });
+  };
+
+  return { copy };
+};
+```
+
+## 兼容性
+
+| 策略                            | 触发条件                                      | 要求                                           |
+| ------------------------------- | --------------------------------------------- | ---------------------------------------------- |
+| `navigator.clipboard.writeText` | 浏览器支持 Clipboard API                      | HTTPS 或 localhost；用户需授权剪贴板权限       |
+| `document.execCommand('copy')`  | 不支持 Clipboard API，或 `writeText` 抛出异常 | 需由用户事件（如 click）直接触发，否则可能失败 |
+
+## 内部使用场景
+
+| 组件               | 用途                                      |
+| ------------------ | ----------------------------------------- |
+| `CodeContent`      | 复制代码块，取 `codeRef.value?.innerText` |
+| `MessageContainer` | 复制 AI 消息内容                          |
+| `UserMessage`      | 复制用户消息内容                          |
+
+## 注意事项
+
+1. **结果不对外暴露**：`copy` 返回 `Promise<void>`，调用方无法获知成功/失败；如需自定义通知，不应使用此 composable
+2. **通知使用 i18n**：消息文本通过 `t()` 函数处理，在多语言环境下自动切换，无法在外部覆盖
+3. **`isClipboardApiSupported` 模块级检测**：在文件 import 时执行一次（非响应式），SSR 环境下 `navigator` 为 `undefined` 时安全降级
+4. **`execCommand` 已废弃**：降级路径依赖 `document.execCommand('copy')`，该 API 在部分浏览器已标记废弃，但目前仍广泛可用
+5. **用户手势要求**：在没有用户交互上下文时（如定时器回调），两种方式都可能失败
+
+## 关联组件
+
+- [CodeContent](../components/atomic/code-content.md) — 代码块复制
+- [MessageContainer](../components/molecular/message-container.md) — 助手消息复制
+- [UserMessage](../components/molecular/user-message.md) — 用户消息复制

package/dist/mcp/generated/docs/use-command-selection.md

@@ -0,0 +1,128 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useCommandSelection 无参数，返回 commandSelection（ShallowRef 行列）与 GetCursorPosition（edix EditorCommand）。 在 editor.command(GetCursorPosition) 时把焦点端写入 commandSelection，供后续 DeleteTag、InsertTag 等命令计算范围。 仅在 AiSlashInput（@ 菜单插入）内部使用。
+
+### 关联组件
+- **chat-input** — AiSlashInput 内部使用
+
+---
+<!-- FULL DOC -->
+
+# useCommandSelection 光标位置追踪
+
+> **分类**：composable
+
+为 `edix` 富文本编辑器提供光标位置追踪能力的组合式函数。内部封装一个 `EditorCommand`，由编辑器调用后将光标的行列信息存入响应式变量，供后续编辑命令（如插入 tag、删除关键词）精确定位。
+
+> 该 composable 仅在 `AiSlashInput` 内部使用，属于编辑器底层基础设施，**通常无需直接调用**。
+
+## 实现原理
+
+```
+editor.command(GetCursorPosition)
+  │  edix 编辑器将 (doc, selection) 注入 EditorCommand
+  │
+  └── GetCursorPosition(doc, selection)
+        const [, focus] = selection   // selection = [anchor, focus]
+        const [line, column] = focus  // focus = [lineIndex, columnIndex]
+        commandSelection.value = { column, line }
+                                 ↓
+               commandSelection（shallowRef，初始值 { column: 0, line: 0 }）
+```
+
+**使用时机**：在 `@` 资源插入流程中，先执行 `GetCursorPosition` 快照当前光标，再据此计算删除范围和插入位置。
+
+## 概念演示
+
+`commandSelection` 追踪编辑器光标的 `{ line, column }` 位置（行从 0 开始，column 为字符偏移量）。以下用原生 textarea 模拟等价的位置信息：
+
+> 实际使用时，由 `editor.command(GetCursorPosition)` 触发写入，而非手动计算。
+
+## 在 AiSlashInput 中的实际用法
+
+```typescript
+const { commandSelection, GetCursorPosition } = useCommandSelection();
+
+// 用户从 @xxx 菜单中选择资源时：
+const insertTagAtCursor = (tag: IAiSlashMenuItem) => {
+  // 1. 执行命令，快照当前光标位置 → 写入 commandSelection.value
+  editor.command(GetCursorPosition);
+
+  // 2. 读取快照的行列位置
+  const { column, line } = commandSelection.value;
+
+  // 3. 根据位置删除已输入的 "@keyword"，插入 tag
+  editor.command(DeleteTag, [line, column - keyword.value.length - 1], [line, column]);
+  editor.command(InsertTag, [line, column], tag);
+};
+```
+
+## API
+
+### 参数
+
+无。`useCommandSelection()` 不接受任何参数。
+
+### 返回值
+
+| 属性名              | 类型                                           | 初始值                   | 说明                                                                                       |
+| ------------------- | ---------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
+| `commandSelection`  | `ShallowRef<{ column: number; line: number }>` | `{ column: 0, line: 0 }` | 存储最近一次执行 `GetCursorPosition` 时的光标行列位置                                      |
+| `GetCursorPosition` | `EditorCommand<[]>`                            | —                        | 编辑器命令，由 `editor.command(GetCursorPosition)` 触发，将当前光标写入 `commandSelection` |
+
+## 类型说明
+
+```typescript
+// EditorCommand：edix 编辑器的命令签名
+type EditorCommand<A extends unknown[]> = (
+  doc: DocFragment,
+  selection: SelectionSnapshot, // [[anchorLine, anchorColumn], [focusLine, focusColumn]]
+  ...args: A
+) => Transaction | void;
+
+// useCommandSelection 返回值
+interface UseCommandSelectionReturn {
+  commandSelection: ShallowRef<{ column: number; line: number }>;
+  GetCursorPosition: EditorCommand<[]>;
+}
+```
+
+## 实现源码
+
+```typescript
+import { shallowRef } from 'vue';
+import type { EditorCommand } from '../edix';
+
+export const useCommandSelection = () => {
+  // 存储最近一次快照的光标位置
+  const commandSelection = shallowRef<{ column: number; line: number }>({
+    column: 0,
+    line: 0,
+  });
+
+  // EditorCommand：由 editor.command() 调用，注入 doc 和 selection
+  const GetCursorPosition: EditorCommand<[]> = (_doc, selection) => {
+    const [, focus] = selection; // 取 focus 端（忽略 anchor）
+    const [line, column] = focus;
+    commandSelection.value = { column, line };
+    // 不返回 Transaction，即只读取不修改文档
+  };
+
+  return {
+    commandSelection,
+    GetCursorPosition,
+  };
+};
+```
+
+## 注意事项
+
+1. **只读命令**：`GetCursorPosition` 不返回 `Transaction`，不修改编辑器文档内容，仅记录位置
+2. **异步快照**：`commandSelection` 在 `editor.command(GetCursorPosition)` 执行后**同步**更新，下一行代码即可安全读取
+3. **`shallowRef` 而非 `ref`**：对象引用替换触发响应式，内部字段修改不触发（此处每次整体替换，无影响）
+4. **仅适用于 edix 编辑器**：`GetCursorPosition` 依赖 edix 的 `SelectionSnapshot` 格式，不适用于原生 contenteditable 或其他富文本库
+
+## 关联组件
+
+- [ChatInput](../components/molecular/chat-input.md) — AiSlashInput 子模块使用

package/dist/mcp/generated/docs/use-container-scroll.md

@@ -0,0 +1,56 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。
+
+### 关联组件
+- **message-container** — Provider 挂载于消息列表滚动区域
+- **scroll-btn** — 使用 debouncedShowScrollBottomBtn 与 toScrollBottom
+- **chat-container** — 组合消息区与输入区时的整体布局上下文
+
+---
+<!-- FULL DOC -->
+
+# useContainerScroll 容器滚动
+
+> **分类**：composable
+
+为消息容器提供滚动控制的组合式函数对，通过 **Provider/Consumer** 模式在父子组件间共享滚动状态。
+
+- `useContainerScrollProvider`：在容器组件中调用，创建滚动控制并通过 `provide` 向下共享
+- `useContainerScrollConsumer`：在任意后代组件中调用，通过 `inject` 获取滚动控制
+
+## 工作原理
+
+```
+useContainerScrollProvider(containerRef, bottomRef)
+  │
+  ├── IntersectionObserver 监听 bottomRef
+  │     可见 → isScrollBottom=true, scrollBottomHeight=0, autoScrollEnabled=true
+  │     不可见 → isScrollBottom=false, calculateScrollBottom()
+  │
+  ├── scroll 事件（passive）→ calculateScrollBottom()
+  │     scrollBottomHeight = max(0, scrollHeight - scrollTop - clientHeight)
+  │
+  ├── wheel 事件（passive）→ deltaY < 0 时 autoScrollEnabled=false
+  │     （用户向上滚动时暂停自动滚动）
+  │
+  ├── toScrollBottom() → autoScrollEnabled=true + bottomRef.scrollIntoView('smooth')
+  ├── toScrollTop()    → containerRef.scrollTo({ top:0, behavior:'smooth' })
+  │
+  └── provide(CONTAINER_SCROLL_TOKEN, computed(() => ({
+            autoScrollEnabled: autoScrollEnabled.value,  // 解包为 boolean
+            isScrollBottom,             // ShallowRef<boolean>（保持响应式）
+            scrollBottomHeight,         // ShallowRef<number>（保持响应式）
+            debouncedShowScrollBottomBtn, // customRef，防抖显示返回底部按钮
+            toScrollBottom,
+            toScrollTop,
+        })))
+
+useContainerScrollConsumer()
+  └── inject(CONTAINER_SCROLL_TOKEN) → ComputedRef<ContainerScrollData> | undefined
+```
+
+> **注意**：Consumer 获得的 `ComputedRef` 中，`isScrollBottom` 和 `scrollBottomHeight` 是 `ShallowRef` 对象（非解包值），需要通过 `.value` 访问。
+
+## 渲染示例