@blueking/chat-x 0.0.5 → 0.0.7

package/dist/mcp/generated/docs/image-preview-group.md

@@ -0,0 +1,181 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ImagePreviewGroup 通过 provide/inject 与子级 symbol 注册表管理多个 AiImage，点击任一子图时聚合已注册图片并打开内置全屏预览。 解决同屏多缩略图统一多图浏览与索引切换的需求。
+
+### 关联组件
+- **ai-image** — 子级注册并参与多图预览集合
+- **image-preview** — 内置实例承载多图切换与工具栏
+
+---
+<!-- FULL DOC -->
+
+# ImagePreviewGroup 图片预览组
+
+> **层级**：分子组件 · **功能域**：文件与图片
+
+多图预览管理容器。通过 `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](../atomic/ai-image.md) — 子级缩略图与注册
+- [ImagePreview](./image-preview.md) — 内置全屏预览

package/dist/mcp/generated/docs/image-preview.md

@@ -0,0 +1,224 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ImagePreview 通过 Teleport 提供全屏图片预览，支持缩放、旋转、拖拽、下载、键盘与多图切换。 数据源可为 URL 字符串、ImageItem 或 File（自动 ObjectURL 并在关闭时回收）。 通常由 AiImage、ImagePreviewGroup、FileContent 等触发，业务较少直接单独挂载。
+
+### 关联组件
+- **ai-image** — 独立模式下由 AiImage 打开预览
+- **image-preview-group** — 组内容器内持有一个实例做多图切换
+- **file-content** — 文件列表点击缩略图触发预览
+
+---
+<!-- FULL DOC -->
+
+# ImagePreview 图片预览
+
+> **层级**：分子组件 · **功能域**：文件与图片
+
+全屏图片预览组件，通过 `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` 数组，在以下时机自动回收：
+>
+> - `images` prop 变化触发 `normalizedImages` 重新计算时
+> - `visible` 从 `true` 变为 `false` 时
+> - 组件 `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](../atomic/ai-image.md) — 独立模式触发预览
+- [ImagePreviewGroup](./image-preview-group.md) — 多图预览容器
+- [FileContent](./file-content.md) — 附件列表点击预览

package/dist/mcp/generated/docs/info-message.md

@@ -0,0 +1,124 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+InfoMessage 以居中虚线分隔条展示系统提示、会话重置、时间戳等非对话信息；content 可为字符串或字符串数组。 由 MessageRender 在 info 角色下渲染，不承载用户与助手轮次内容。
+
+### 关联组件
+- **message-render** — 由 MessageRender 在 role 为 info 时创建
+- **message-container** — 嵌入消息列表时由 MessageContainer 统一布局与滚动
+
+---
+<!-- FULL DOC -->
+
+# InfoMessage 信息消息
+
+> **层级**：分子组件 · **功能域**：消息展示
+
+系统信息分隔组件，在聊天消息列表中以**居中虚线分隔条**的形式展示非对话类信息（会话重置、时间节点、状态变更等）。
+
+## 视觉原理
+
+组件通过 `height: 0` + `border-bottom: 1px dashed #dcdee5` 生成一条贯穿全宽的虚线，内容文字区域设置白色背景"浮"在虚线中央，形成"文字刻在分隔线上"的视觉效果：
+
+```
+───── ─ ─ 以下是新的对话 ─ ─ ─────
+```
+
+## 基础用法
+
+`content` 传入字符串，渲染单行分隔信息：
+
+```vue
+<template>
+  <InfoMessage :content="content" />
+</template>
+
+<script setup lang="ts">
+  import { InfoMessage } from '@blueking/chat-x';
+
+  const content = '以下是新的对话';
+</script>
+```
+
+**渲染效果**
+
+## 多行信息
+
+`content` 传入字符串数组时，每个元素渲染为一个独立的文字浮标，均居中排列在同一条虚线上：
+
+```vue
+<template>
+  <InfoMessage :content="['会话已重置', '以下是新的对话']" />
+</template>
+
+<script setup lang="ts">
+  import { InfoMessage } from '@blueking/chat-x';
+</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/dist/mcp/generated/docs/key-value-content.md

@@ -0,0 +1,124 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+KeyValueContent 以多行 key : value 形式展示结构化数据，可选标题栏与 ThinkingIcon。 常见于用户消息等需要表格化键值的气泡展示。
+
+### 关联组件
+- **user-message** — 用户消息内展示结构化附加信息
+
+---
+<!-- FULL DOC -->
+
+# KeyValueContent 键值对内容
+
+> **层级**：原子组件 · **功能域**：辅助组件
+
+键值对列表展示原子组件，每行以 `key : value` 格式渲染一条数据，支持可选标题栏（带 `ThinkingIcon`）。
+
+主要被 `UserMessage` 内部用于渲染结构化引用内容（`property.extra.cite.data`），通常不需要手动引入。
+
+## 组件结构
+
+```
+div.ai-key-value-content（flex column，gap: 8px，font-size: 12px，color: #4d4f56）
+├── [v-if="title"] div.ai-key-value-title（flex，gap: 4px，font-size: 12px，font-weight: 700，color: #3a84ff）
+│     ├── ThinkingIcon（14×14px）
+│     └── {{ title }}
+└── div.ai-key-value-content（flex column，无 gap）   ← 与外层同名嵌套
+      └── div.key-value-item × N（flex row，gap: 3px，height: 20px）
+            ├── div.item-key   → {{ item.key }}（font-weight: bold，color: #333）
+            ├── "："            → 硬编码文本节点，冒号不属于任何 div
+            └── div.item-value → {{ item.value }}（overflow hidden，ellipsis，nowrap）
+```
+
+> **注意**：内层也是 `.ai-key-value-content` 类（与外层同名），仅用于布局，无额外样式差异。  
+> **注意**：`v-for` 使用 `item.key` 作为 `:key`，`content` 中的 `key` 字段必须唯一，否则触发 Vue 重复 key 警告。  
+> **注意**：`item.value` 使用 `text-overflow: ellipsis` 截断，但**无 tooltip**（与 `DescPanel` 不同），过长内容会被静默截断。
+
+## 基础用法
+
+```vue
+<template>
+  <KeyValueContent :content="data" />
+</template>
+
+<script setup lang="ts">
+  import { KeyValueContent } from '@blueking/chat-x';
+
+  const data = [
+    { key: '名称', value: '蓝鲸智云' },
+    { key: '版本', value: 'v3.0' },
+    { key: '状态', value: '运行中' },
+  ];
+</script>
+```
+
+## 带标题
+
+传入 `title` 时，顶部显示 `ThinkingIcon` + 标题文本（蓝色加粗）：
+
+```vue
+<template>
+  <KeyValueContent
+    title="模型参数"
+    :content="[
+      { key: '模型', value: 'GPT-4' },
+      { key: '温度', value: '0.7' },
+      { key: '最大 Token', value: '2048' },
+      { key: '频率惩罚', value: '0.5' },
+    ]"
+  />
+</template>
+```
+
+## 超长 value 截断
+
+`.item-value` 固定 `white-space: nowrap`，超出容器宽度时截断显示省略号，**悬停无 tooltip**：
+
+## API
+
+### Props
+
+| 属性名  | 类型                                | 必填 | 说明                                                              |
+| ------- | ----------------------------------- | ---- | ----------------------------------------------------------------- |
+| content | `{ key: string; value: string; }[]` | ✓    | 键值对数组；`key` 同时作为 `v-for` 的 `:key`，需保证唯一          |
+| title   | `string`                            | —    | 标题文本；传入后在列表上方渲染 `ThinkingIcon + title`（蓝色加粗） |
+
+## 使用场景
+
+`KeyValueContent` 由 `UserMessage` 内部使用，渲染结构化引用内容（`property.extra.cite` 为对象类型时）：
+
+```typescript
+// UserMessage 内部逻辑（简化）
+const citeTitle = computed(() => {
+  const cite = props.property?.extra?.cite;
+  return cite && typeof cite !== 'string' ? cite.title : undefined;
+});
+
+const citeContent = computed(() => {
+  const cite = props.property?.extra?.cite;
+  return cite && typeof cite !== 'string' ? cite.data : cite;
+});
+// citeContent 为数组时 → <KeyValueContent :content="citeContent" :title="citeTitle" />
+// citeContent 为字符串时 → <CiteContent :content="citeContent" />
+```
+
+如需在用户消息中展示结构化引用，将 `property.extra.cite` 设置为以下格式即可：
+
+```typescript
+const message = {
+  // ...
+  property: {
+    extra: {
+      cite: {
+        title: '引用标题',
+        data: [{ key: '字段名', value: '字段值' }],
+      },
+    },
+  },
+};
+```
+
+## 关联组件
+
+- [UserMessage](../molecular/user-message.md) — 键值气泡展示