@blueking/chat-x 0.0.50 → 0.0.51-beta.2

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

@@ -0,0 +1,184 @@
+# ImagePreviewGroup 图片预览组
+
+> 能力域：媒体文件 ｜ 导入：`import { ImagePreviewGroup } from '@blueking/chat-x'` ｜ since 1.0.0
+
+通过 provide/inject 管理同组图片预览。 源码位置：src/components/image-preview/image-preview-group.vue。
+
+**关联**：ai-image（子级注册并参与多图预览集合）、image-preview（内置实例承载多图切换与工具栏）
+
+---
+
+# ImagePreviewGroup 图片预览组
+## 源码事实
+
+- **源码位置**：`src/components/image-preview/image-preview-group.vue`
+- **能力域**：媒体文件
+- **能力说明**：通过 provide/inject 管理同组图片预览。
+
+> **能力域**：媒体文件
+
+多图预览管理容器。通过 `provide/inject` + `Map<symbol>` 模式管理子级 `AiImage` 的注册与预览状态，点击任意子图片时自动收集所有已注册图片并打开多图预览。
+
+## 组件结构
+
+```
+.ai-image-preview-group
+├── <slot />（放置多个 AiImage）
+└── ImagePreview（内置，按需显示）
+      v-model:visible="previewVisible"
+      v-model:current="activeIndex"
+      :images="previewImages"
+```
+
+## 工作原理
+
+```
+┌─ ImagePreviewGroup ──────────────────────────────────────┐
+│  provide(IMAGE_PREVIEW_GROUP_KEY, { register, unregister, preview })  │
+│                                                                       │
+│  ┌─ AiImage ─┐  ┌─ AiImage ─┐  ┌─ AiImage ─┐                       │
+│  │ uid: sym1 │  │ uid: sym2 │  │ uid: sym3 │                        │
+│  │ onMounted → register(sym, getItem)                                 │
+│  │ onClick  → groupContext.preview(sym)                               │
+│  │ onUnmount → unregister(sym)                                        │
+│  └────────────┘  └────────────┘  └────────────┘                       │
+│                                                                       │
+│  preview(uid) → 收集所有 registry 中的 ImageItem →                    │
+│                  设置 activeIndex → 打开 ImagePreview                  │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+## 基础用法
+
+```vue
+<template>
+  <ImagePreviewGroup>
+    <AiImage
+      v-for="(src, i) in images"
+      :key="i"
+      :src="src"
+      :width="160"
+      :height="120"
+    />
+  </ImagePreviewGroup>
+</template>
+
+<script setup lang="ts">
+  import { AiImage, ImagePreviewGroup } from '@blueking/chat-x';
+
+  const images = [
+    'https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=300&fit=crop',
+    'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=300&fit=crop',
+    'https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=400&h=300&fit=crop',
+  ];
+</script>
+```
+
+## 带图片信息
+
+配合 `showInfo` 和 `AiImage` 的 `previewProps`，在预览工具栏显示图片尺寸信息：
+
+```vue
+<template>
+  <ImagePreviewGroup :show-info="true">
+    <AiImage
+      v-for="(img, i) in images"
+      :key="i"
+      :src="img.src"
+      :preview-props="img.previewProps"
+      :width="160"
+      :height="120"
+    />
+  </ImagePreviewGroup>
+</template>
+
+<script setup lang="ts">
+  import { AiImage, ImagePreviewGroup, type ImagePreviewConfig } from '@blueking/chat-x';
+
+  const images = [
+    {
+      src: '...缩略图地址...',
+      previewProps: {
+        src: '...高清原图地址...',
+        name: '湖泊风景.jpg',
+        width: 1920,
+        resolution: '1920×1080',
+      } as ImagePreviewConfig,
+    },
+    // ...更多图片
+  ];
+</script>
+```
+
+## 自定义下载
+
+通过 `onDownload` 统一控制所有子图片的下载行为：
+
+```vue
+<template>
+  <ImagePreviewGroup :on-download="handleDownload">
+    <AiImage
+      v-for="(src, i) in images"
+      :key="i"
+      :src="src"
+      :width="160"
+      :height="120"
+    />
+  </ImagePreviewGroup>
+</template>
+
+<script setup lang="ts">
+  import { AiImage, ImagePreviewGroup } from '@blueking/chat-x';
+
+  const handleDownload = (url: string) => {
+    window.open(`/api/download?url=${encodeURIComponent(url)}`);
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型                    | 默认值  | 说明                                          |
+| ------------ | ----------------------- | ------- | --------------------------------------------- |
+| maskClosable | `boolean`               | `true`  | 点击遮罩层是否关闭预览                        |
+| showInfo     | `boolean`               | `false` | 预览工具栏是否显示图片尺寸信息                |
+| onDownload   | `(url: string) => void` | —       | 自定义下载回调；不传时使用默认 `<a>` 标签下载 |
+
+### Slots
+
+| 插槽名  | 说明                                            |
+| ------- | ----------------------------------------------- |
+| default | 放置子级 `AiImage` 组件                         |
+| extra   | 预览工具栏的额外操作区域（透传给 ImagePreview） |
+
+## 类型定义
+
+```typescript
+interface ImagePreviewGroupContext {
+  register: (uid: symbol, getItem: () => ImageItem) => void;
+  unregister: (uid: symbol) => void;
+  preview: (uid: symbol) => void;
+}
+
+const IMAGE_PREVIEW_GROUP_KEY: InjectionKey<ImagePreviewGroupContext>;
+```
+
+## 与 AiImage 的协作关系
+
+| AiImage 场景  | 行为                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------- |
+| 未在 Group 内 | `inject` 返回 `null`，AiImage 内部自行渲染 `ImagePreview`（独立模式）                    |
+| 在 Group 内   | `inject` 获取 Group 上下文；`onMounted` 注册自身；点击时调用 `groupContext.preview(uid)` |
+
+## 使用场景
+
+- AI 对话中一条消息包含多张图片，需要统一预览
+- 图片画廊场景
+- 任何需要"点击缩略图 → 多图预览切换"的场景
+
+## 关联组件
+
+- [AiImage](/components/medias/ai-image) — 子级缩略图与注册
+- [ImagePreview](/components/medias/image-preview) — 内置全屏预览

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

@@ -0,0 +1,226 @@
+# ImagePreview 图片预览
+
+> 能力域：媒体文件 ｜ 导入：`import { ImagePreview } from '@blueking/chat-x'` ｜ since 1.0.0
+
+图片全屏预览容器，支持缩放、旋转、下载工具栏。 源码位置：src/components/image-preview/image-preview.vue。
+
+**关联**：ai-image（独立模式下由 AiImage 打开预览）、image-preview-group（组内容器内持有一个实例做多图切换）、file-content（文件列表点击缩略图触发预览）
+
+---
+
+# ImagePreview 图片预览
+## 源码事实
+
+- **源码位置**：`src/components/image-preview/image-preview.vue`
+- **能力域**：媒体文件
+- **能力说明**：图片全屏预览容器，支持缩放、旋转、下载工具栏。
+
+> **能力域**：媒体文件
+
+全屏图片预览组件，通过 `Teleport` 渲染到 `body`，支持缩放、旋转、拖拽、下载、键盘导航等功能。`images` 支持传入 URL 字符串、`ImageItem` 对象或 `File` 对象，File 对象会自动通过 `URL.createObjectURL` 生成预览并在关闭/卸载时回收。通常不直接使用，而是配合 `AiImage`、`ImagePreviewGroup` 或 `FileContent` 自动触发。
+
+## 组件结构
+
+```
+Teleport(to="body")
+└── .ai-image-preview（fixed，z-index: 10000，background: rgba(0,0,0,0.6)）
+    ├── .ai-image-preview-close（右上角关闭按钮）
+    ├── .ai-image-preview-arrow-left（左切换箭头，多图时显示）
+    ├── .ai-image-preview-arrow-right（右切换箭头，多图时显示）
+    ├── .ai-image-preview-body（图片主体区域，支持拖拽/滚轮缩放）
+    │   ├── <img>（currentStatus !== 'error' 时）
+    │   ├── .ai-image-preview-error（加载失败时）
+    │   └── .ai-image-preview-loading（加载中，支持模糊缩略图）
+    └── PreviewToolbar（底部工具栏）
+        ├── 页码（多图时: 1/3）
+        ├── 缩小 / 放大 / 旋转 / 重置 / 下载
+        ├── slot#extra（额外操作区域）
+        └── 图片信息（showInfo 时显示宽度/分辨率）
+```
+
+## 内部子组件
+
+### PreviewToolbar
+
+底部圆角工具栏，包含以下按钮：
+
+| 按钮 | 功能                           | tooltip |
+| ---- | ------------------------------ | ------- |
+| 缩小 | 按 15% 步进缩小（最小 0.1 倍） | 缩小    |
+| 放大 | 按 15% 步进放大（最大 10 倍）  | 放大    |
+| 旋转 | 顺时针旋转 90°                 | 旋转    |
+| 重置 | 重置缩放/旋转/位移             | 重置    |
+| 下载 | 触发下载                       | 下载    |
+
+多图模式下还显示页码（如 "1 / 3"）和分隔线。
+
+### useImageTransform
+
+图片变换 Composable，管理缩放/旋转/平移状态：
+
+- `scale`：缩放比例（0.1 ~ 10，步进 15%）
+- `rotate`：旋转角度（每次 +90°，累加不取模）
+- `translateX / translateY`：拖拽偏移量
+- 支持鼠标滚轮缩放和拖拽平移
+- `resetTransform` 重置时跳过过渡动画（`skipTransition`），避免视觉闪烁
+
+### usePreviewKeyboard
+
+键盘导航 Composable：
+
+| 按键  | 功能               |
+| ----- | ------------------ |
+| `Esc` | 关闭预览           |
+| `←`   | 上一张（多图模式） |
+| `→`   | 下一张（多图模式） |
+
+预览打开时自动锁定 `body` 滚动（`overflow: hidden`），关闭时恢复。
+
+## 基础用法（单图）
+
+```vue
+<template>
+  <button @click="visible = true">预览图片</button>
+  <ImagePreview
+    v-model:visible="visible"
+    :images="images"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ImagePreview } from '@blueking/chat-x';
+
+  const visible = ref(false);
+  const images = ['https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=1920'];
+</script>
+```
+
+## 多图预览
+
+传入多张图片时，左右箭头和页码自动显示，支持循环切换：
+
+```vue
+<template>
+  <button @click="visibleMulti = true">预览多张图片</button>
+  <ImagePreview
+    v-model:visible="visibleMulti"
+    v-model:current="currentIndex"
+    :images="images"
+    :show-info="true"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ImagePreview, type ImageItem } from '@blueking/chat-x';
+
+  const visibleMulti = ref(false);
+  const currentIndex = ref(0);
+  const images: ImageItem[] = [
+    { url: '...', name: '湖泊风景.jpg', width: 1920, resolution: '1920×1080' },
+    { url: '...', name: '山谷日出.jpg', width: 1920, resolution: '1920×1280' },
+    { url: '...', name: '森林小径.jpg', width: 1920, resolution: '1920×1280' },
+  ];
+</script>
+```
+
+## File 对象预览
+
+`images` 数组中可直接传入 `File` 对象，组件会自动通过 `URL.createObjectURL` 生成预览 URL，并在预览关闭或组件卸载时自动调用 `URL.revokeObjectURL` 释放内存：
+
+```vue
+<template>
+  <button @click="visibleFile = true">预览 File 对象</button>
+  <ImagePreview
+    v-model:visible="visibleFile"
+    :images="fileImages"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ImagePreview } from '@blueking/chat-x';
+
+  const visibleFile = ref(false);
+  const fileImages = [
+    new File(['png-data'], 'screenshot.png', { type: 'image/png' }),
+    new File(['jpg-data'], 'photo.jpg', { type: 'image/jpeg' }),
+  ];
+</script>
+```
+
+> **ObjectURL 生命周期管理**：组件内部维护 `objectUrls` 数组，在以下时机自动回收：
+>
+> - `normalizedImages` 计算属性重算时（会先 `revokeObjectUrls`，再按当前 `images` 与 `visible` 生成新列表）
+> - **`visible` 为 `false` 时**：计算属性直接清空并 `revokeObjectURL`，避免仅依赖 `props.images` 时 computed 仍缓存**已失效**的 blob URL，导致关闭预览后再次打开加载失败
+> - 组件 `onBeforeUnmount` 时
+
+## API
+
+### Props
+
+| 属性名       | 类型                              | 默认值  | 说明                                                        |
+| ------------ | --------------------------------- | ------- | ----------------------------------------------------------- |
+| images       | `(File \| ImageItem \| string)[]` | `[]`    | 图片列表；字符串自动转为 `{ url }`，File 自动转为 ObjectURL |
+| maskClosable | `boolean`                         | `true`  | 点击遮罩层是否关闭预览                                      |
+| showInfo     | `boolean`                         | `false` | 工具栏是否显示图片尺寸信息（width / resolution）            |
+| onDownload   | `(url: string) => void`           | —       | 自定义下载回调；不传时使用默认 `<a>` 标签下载               |
+
+### v-model
+
+| 属性名  | 类型      | 必填 | 说明                    |
+| ------- | --------- | ---- | ----------------------- |
+| visible | `boolean` | ✅   | 控制预览弹窗的显示/隐藏 |
+| current | `number`  | —    | 当前展示的图片索引      |
+
+### Slots
+
+| 插槽名 | 说明                                   |
+| ------ | -------------------------------------- |
+| extra  | 工具栏额外操作区域，渲染在下载按钮右侧 |
+
+## 类型定义
+
+```typescript
+interface ImageItem {
+  url: string;
+  thumbnailUrl?: string;
+  name?: string;
+  file?: File;
+  width?: number;
+  height?: number;
+  resolution?: string;
+  downloadUrl?: string;
+}
+
+type ImageLoadingStatus = 'loading' | 'loaded' | 'error';
+```
+
+## 交互说明
+
+| 操作          | 效果                                    |
+| ------------- | --------------------------------------- |
+| 滚轮向上      | 放大图片（15% 步进）                    |
+| 滚轮向下      | 缩小图片（15% 步进）                    |
+| 鼠标左键拖拽  | 平移图片                                |
+| 点击遮罩      | 关闭预览（`maskClosable` 为 `true` 时） |
+| 点击关闭按钮  | 关闭预览                                |
+| 左/右箭头按钮 | 切换上/下一张（多图，循环切换）         |
+| `Esc` 键      | 关闭预览                                |
+| `←` / `→` 键  | 切换上/下一张（多图）                   |
+
+## 使用场景
+
+- 单张或多张图片的全屏预览
+- AI 对话中点击图片放大查看（由 `AiImage` 自动触发）
+- 文件列表中点击图片缩略图预览（由 `FileContent` 内部集成）
+- 用户消息中点击附件图片预览（由 `UserMessage` → `FileContent` 自动触发）
+- 需要旋转/缩放/下载操作的图片查看
+- 传入 `File` 对象直接预览（无需手动管理 ObjectURL）
+
+## 关联组件
+
+- [AiImage](/components/medias/ai-image) — 独立模式触发预览
+- [ImagePreviewGroup](/components/medias/image-preview-group) — 多图预览容器
+- [FileContent](/components/medias/file-content) — 附件列表点击预览

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

@@ -0,0 +1,144 @@
+# InfoMessage 信息消息
+
+> 能力域：消息系统 ｜ 导入：`import { InfoMessage } from '@blueking/chat-x'` ｜ since 0.0.20
+
+渲染居中的系统信息提示。 源码位置：src/components/chat-message/info-message/info-message.vue。
+
+**关联**：message-render（由 MessageRender 在 role 为 info 时创建）、message-container（嵌入消息列表时由 MessageContainer 统一布局与滚动）
+
+---
+
+# InfoMessage 信息消息
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/info-message/info-message.vue`
+- **能力域**：消息系统
+- **能力说明**：渲染居中的系统信息提示。
+
+> **导出说明**：`InfoMessage` **未**从包入口导出（入口同名是 TS interface）。消费方经 `MessageRender` / `MessageContainer` 使用。下文 `InfoMessageComp` 为文档站内部示例。
+
+系统信息分隔组件，在聊天消息列表中以**左右虚线夹中文案**的形式展示非对话类信息（会话重置、时间节点、状态变更等）。
+
+## 视觉原理
+
+根节点 `.ai-info-message` 为横向 flex：两侧通过 `::before` / `::after` 拉伸出虚线（主题边框色），中间 `.ai-info-message-body` 承载文案（主题次要文案色）。整块正常占位，避免旧实现 `height: 0` 导致内容被裁切遮挡：
+
+```
+─────── 以下是新的对话 ───────
+```
+
+多行时，多条 `.ai-info-message-content` 在 body 内纵向排列（`gap: 4px`），两侧虚线仍夹住整块文案区域。
+## 基础用法
+
+`content` 传入字符串，渲染单行分隔信息：
+
+```vue
+<template>
+  <MessageRender :message="message" />
+</template>
+
+<script setup lang="ts">
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Info,
+    content: '以下是新的对话',
+    status: MessageStatus.Complete,
+  };
+</script>
+```
+
+**渲染效果**
+
+## 多行信息
+
+`content` 传入字符串数组时，每个元素渲染为一行居中文案，在中间 body 内纵向排列，两侧虚线夹住整块区域：
+
+```vue
+<template>
+  <MessageRender :message="message" />
+</template>
+
+<script setup lang="ts">
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  // 运行时 content 兼容 string[]（TS 类型声明多为 string）
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Info,
+    content: ['会话已重置', '以下是新的对话'],
+    status: MessageStatus.Complete,
+  };
+</script>
+```
+
+**渲染效果**
+
+## 典型使用场景
+
+**会话分隔**
+
+**时间节点**
+
+**上下文清除**
+
+## 在 MessageContainer 中使用
+
+`InfoMessage` 通常不需要单独引入，`MessageContainer`（或 `MessageRender`）会对 `role: 'info'` 的消息自动渲染：
+
+```vue
+<template>
+  <MessageContainer :messages="messages" />
+</template>
+
+<script setup lang="ts">
+  import { MessageContainer, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const messages = [
+    {
+      id: '1',
+      messageId: '1',
+      role: MessageRole.User,
+      content: '请帮我分析一下这份报告。',
+      status: MessageStatus.Complete,
+    },
+    // info 消息：role 为 'info'，content 为字符串
+    {
+      id: '2',
+      messageId: '2',
+      role: MessageRole.Info, // 'info'
+      content: '上下文已达上限，已自动清除历史对话',
+      status: MessageStatus.Complete,
+    },
+    {
+      id: '3',
+      messageId: '3',
+      role: MessageRole.Assistant,
+      content: '好的，我来帮你分析这份报告...',
+      status: MessageStatus.Complete,
+    },
+  ];
+</script>
+```
+
+## API
+
+### Props
+
+组件 Props 继承自 `Partial<InfoMessage>`，所有字段均可选：
+
+| 属性名    | 类型                 | 说明                                                               |
+| --------- | -------------------- | ------------------------------------------------------------------ |
+| content   | `string \| string[]` | 信息内容。字符串渲染单行；数组在中间区域纵向多行展示，两侧虚线夹住整块 |
+| id        | `number \| string`   | 消息 ID（接收但不使用，由 MessageContainer 管理）                  |
+| messageId | `number \| string`   | 消息唯一标识（接收但不使用）                                       |
+| status    | `MessageStatus`      | 消息状态（接收但不使用，组件无状态相关渲染逻辑）                   |
+| role      | `MessageRole.Info`   | 消息角色，固定为 `'info'`                                          |
+
+> **说明**：`content` 的 TypeScript 类型定义为 `string`（与 `BaseMessage` 泛型一致），但组件模板内部通过 `Array.isArray(content) ? content : [content]` 实际兼容字符串数组。
+
+## 安全性

package/skills/blueking-chat-x/references/components/input-attachment.md

@@ -0,0 +1,49 @@
+# InputAttachment 输入附件区
+
+> 能力域：输入交互 ｜ 导入：`import { InputAttachment } from '@blueking/chat-x'` ｜ since 1.0.0
+
+ChatInput 底部附件区布局，承载快捷按钮、文件与发送图标。 源码位置：src/components/chat-input/input-attachment/input-attachment.vue。
+
+---
+
+# InputAttachment 输入附件区
+
+> **能力域**：输入交互
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-input/input-attachment/input-attachment.vue`
+- **能力说明**：ChatInput 底部附件区布局，承载快捷按钮、文件与发送图标。
+- **交互说明**：
+  - `sendMessage` 点击绑定在 `.send-message-icon` 容器上（覆盖图标与按钮空白区域），而非仅绑定在 `SendMessageIcon` 上。
+  - `Streaming` / `Pending` / `Fetching` 时展示 `LoadingMessageIcon`，点击发出 `stopSending`。
+  - `Disabled`、`sendDisabledTip`、`Pending`、`Streaming` 状态下点击发送容器不会发出 `sendMessage`。
+
+## API 摘要
+
+### Props
+
+- `{ messageState?: MessageStatus; sendDisabledTip?: string; tippyOptions?: AITippyProps; }`
+
+### Emits
+
+- `{ (e: 'sendMessage'): void; (e: 'stopSending'): void; }`
+
+### Slots
+
+- `default`
+- `before-send`（发送按钮左侧区域，ChatInput 默认在此渲染 ModelSelector）
+- `send-icon`
+
+### Expose
+
+- 无。
+
+## 组件依赖
+
+- 无组件依赖或仅依赖基础库。
+
+## 使用建议
+
+- 优先通过上层组合组件使用；直接使用前请确认 props 数据结构来自对应类型定义。
+- 自定义 `send-icon` 插槽时需自行处理发送/停止点击逻辑。

package/skills/blueking-chat-x/references/components/input-info-alert.md

@@ -0,0 +1,42 @@
+# InputInfoAlert 输入提示条
+
+> 能力域：输入交互 ｜ 导入：`import { InputInfoAlert } from '@blueking/chat-x'` ｜ since 1.0.0
+
+ChatInput 上方的信息提示条。 源码位置：src/components/chat-input/input-info-alert.vue。
+
+---
+
+# InputInfoAlert 输入提示条
+
+> **能力域**：输入交互
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-input/input-info-alert.vue`
+- **能力说明**：ChatInput 上方的信息提示条。
+
+## API 摘要
+
+### Props
+
+- `{ content: string; }`
+
+### Emits
+
+- 无。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 组件依赖
+
+- 无组件依赖或仅依赖基础库。
+
+## 使用建议
+
+- 优先通过上层组合组件使用；直接使用前请确认 props 数据结构来自对应类型定义。