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

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

@@ -0,0 +1,182 @@
+# ImageContent 图片内容
+
+> 能力域：媒体文件 ｜ 导入：`import { ImageContent } from '@blueking/chat-x'` ｜ since 1.0.0
+
+渲染 Markdown 图片 token。 源码位置：src/components/markdown-token/image-content/image-content.vue。
+
+**关联**：markdown-content（解析图片 token 后挂载本组件）
+
+---
+
+# ImageContent 图片渲染
+## 源码事实
+
+- **源码位置**：`src/components/markdown-token/image-content/image-content.vue`
+- **能力域**：媒体文件
+- **能力说明**：渲染 Markdown 图片 token。
+
+> **能力域**：媒体文件
+
+Markdown Token 层的图片渲染基础组件，被 `MarkdownContent` 在解析到图片 token 时自动调用，通常无需手动引入。
+
+核心能力：**流式 URL 防闪烁**（debounce 稳定判断 + throttle 预加载）、**全局缓存**（模块级 `Set` 跨实例共享）、**三态渲染**（加载中 / 成功 / 失败）。
+
+## 组件结构
+
+```
+span.ai-md-image-wrapper（inline-block，vertical-align: middle）
+├── [showLoading] span.md-image-loading（inline-flex，gap: 6px，padding: 4px 8px，bg: #f5f7fa）
+│     ├── bkui-vue Loading（spin，mini，primary）
+│     └── "图片加载中..."
+├── [showError]  span.md-image-error（同上，color: #ea3636，bg: #fee）
+│     ├── span.md-image-error-icon  →  ⚠️（font-size: 14px）
+│     └── span.md-image-error-text  →  alt || "图片加载失败"
+└── [else]       img.md-image（max-width: 100%，height: auto，loading="lazy"）
+                   :src="src"  :alt="alt"
+```
+
+> **错误文本**：优先显示 `alt`，未传 `alt` 时才显示 "图片加载失败"。
+
+## 状态机
+
+组件内部维护三个 `shallowRef`：`isLoading`、`hasError`、`isUrlStable`，以及两个 computed 控制显示：
+
+```
+showLoading 为 true 的条件（按优先级）：
+  1. isCached（全局缓存命中）→ false，直接显示图片
+  2. !isValidUrl              → true（URL 无效或正在输入中）
+  3. isLoading               → true（正在预加载）
+  4. !isUrlStable && hasError → true（URL 仍在变化，忽略旧错误）
+
+showError 为 true 的条件（需全部满足）：
+  isUrlStable && hasError && !isLoading
+```
+
+### URL 有效性（isValidUrl）
+
+```
+src 被判定为无效的情况（显示 Loading）：
+  · 空字符串 / '#' / '#)'
+  · 以 '#' 或 '#)' 结尾（Markdown 语法补全占位符）
+  · 无协议且不是相对路径/带图片扩展名的路径
+  · https?:// 开头但域名中无 '.' 且不是 localhost
+
+合法 URL 格式：
+  · https?://、//          → 协议 URL（域名需含 '.' 或为 localhost）
+  · data:、blob:           → Data URL / Blob URL
+  · /path 或 ./path       → 绝对/相对路径
+  · image.png、a.jpg?v=1  → 带图片扩展名的文件名
+```
+
+### 流式防抖与节流
+
+| 机制                        | 参数                      | 作用                                                             |
+| --------------------------- | ------------------------- | ---------------------------------------------------------------- |
+| `markUrlStable`（debounce） | 500ms                     | URL 停止变化 500ms 后置 `isUrlStable = true`，此后才允许显示错误 |
+| `preloadImage`（throttle）  | 100ms，leading + trailing | 限制 `new Image()` 预加载频率，流式输入时不会每个字符都发请求    |
+
+### 全局缓存
+
+`loadedImageCache` 是**模块级 `Set<string>`**，所有 `ImageContent` 实例共享：
+
+- 图片加载成功后 → `loadedImageCache.add(url)`
+- 组件初始化时若命中缓存 → `isLoading = false`，`isUrlStable = true`，跳过所有预加载逻辑，直接渲染 `<img>`
+- 页面刷新后缓存清空（仅内存缓存）
+
+## 基础用法
+
+```vue
+<template>
+  <ImageContent
+    src="https://picsum.photos/seed/demo/400/200"
+    alt="示例图片"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ImageContent } from '@blueking/chat-x';
+</script>
+```
+
+## 加载失败
+
+URL 稳定后（500ms 无变化）加载失败，显示 `⚠️ + alt文本`（无 alt 时显示"图片加载失败"）：
+
+## Data URL
+
+支持 Base64 / SVG Data URL，不经过 `isValidUrl` 的网络检测，直接进入预加载：
+
+```vue
+<template>
+  <ImageContent
+    src="data:image/svg+xml,..."
+    alt="内联 SVG"
+  />
+</template>
+```
+
+## 流式输入防闪烁
+
+流式 Markdown 渲染时 URL 逐字符拼接，组件通过 debounce + throttle 避免频繁请求和闪烁：
+
+```vue
+<template>
+  <button
+    @click="simulateStreaming"
+    :disabled="isStreaming"
+  >
+    {{ isStreaming ? '输入中...' : '模拟流式输入' }}
+  </button>
+  <ImageContent
+    :src="streamingUrl"
+    alt="流式图片"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ImageContent } from '@blueking/chat-x';
+
+  const streamingUrl = ref('');
+  const isStreaming = ref(false);
+
+  const simulateStreaming = async () => {
+    const url = 'https://picsum.photos/seed/chat-x-stream/400/200';
+    streamingUrl.value = '';
+    isStreaming.value = true;
+    for (let i = 0; i <= url.length; i++) {
+      await new Promise(r => setTimeout(r, 60));
+      streamingUrl.value = url.slice(0, i);
+    }
+    isStreaming.value = false;
+  };
+</script>
+```
+
+**流式过程中的状态变化**：
+
+```
+URL = ''             → isValidUrl=false  → showLoading=true（Loading）
+URL = 'https://'    → isValidUrl=false  → showLoading=true（域名不完整）
+URL = 'https://p…'  → isValidUrl=false  → showLoading=true（域名无 '.'）
+URL = 完整 URL       → isValidUrl=true   → throttle 触发 preloadImage
+                                           debounce 500ms → isUrlStable=true
+                                           onload → cache → showLoading=false → 显示图片
+```
+
+## API
+
+### Props
+
+| 属性名 | 类型     | 必填 | 说明                                                                         |
+| ------ | -------- | ---- | ---------------------------------------------------------------------------- |
+| src    | `string` | ✓    | 图片 URL，支持 https / http / // / data: / blob: / 相对路径 / 带扩展名文件名 |
+| alt    | `string` | —    | 替代文本；加载失败时优先显示此文本，未传时显示"图片加载失败"                 |
+
+## 使用场景
+
+`ImageContent` 由 `MarkdownContent` 在渲染 `image` token 时自动调用，通常不需要手动引入。如需在 Markdown 以外的场景渲染带流式防抖保护的图片，可单独使用。
+
+## 关联组件
+
+- [MarkdownContent](/components/rendering/markdown-content) — 图片 token 渲染入口

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) — 附件列表点击预览