@blueking/chat-x 0.0.5 → 0.0.6

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

@@ -0,0 +1,428 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ActivityMessage 展示活动类消息：知识检索（knowledge_rag）、引用文档列表、FlowAgent 执行（activityType 区分），标题可折叠。 content 结构随模式变化。由 MessageRender 在 activity 角色下渲染，用于 RAG/引用/流程执行过程可视化。
+
+### 关联组件
+- **message-render** — 由 MessageRender 在 role 为 activity 时创建
+- **flow-message** — 与流程编排执行可视化同属一类场景，组件形态不同
+- **assistant-message** — 常与助手回复相邻，描述检索或执行背景
+
+---
+<!-- FULL DOC -->
+
+# ActivityMessage 活动消息
+
+> **层级**：分子组件 · **功能域**：消息展示
+
+活动消息组件，用于展示 AI 的知识检索（Knowledge RAG）过程、参考文档引用列表和 FlowAgent 流程执行情况。通过 `activityType` 切换三种工作模式，点击标题栏可折叠/展开内容区域。
+
+## 三种工作模式
+
+组件根据 `activityType` 的值决定渲染模式：
+
+| `activityType`    | 模式           | 标题文案                             | 图标             | 内容区                              |
+| ----------------- | -------------- | ------------------------------------ | ---------------- | ----------------------------------- |
+| `'knowledge_rag'` | 知识检索模式   | 检索中 / 检索完成（随 status 切换）  | Loading / 文档   | Markdown 检索摘要 + 引用列表        |
+| `'flow-agent'`    | FlowAgent 模式 | 执行情况: 成功 N / 失败 N / 执行中 N | Loading / 箭头   | 任务节点树 + 节点详情（自定义 Tab） |
+| 其他任意值        | 引用文档模式   | 引用 N 篇资料作为参考                | 文档图标（固定） | 引用文档列表                        |
+
+> **注意：** 只有值严格等于 `'knowledge_rag'` 才进入知识检索模式；严格等于 `'flow-agent'`（`MessageContentType.FlowAgent`）才进入 FlowAgent 模式；其他值均按引用文档模式处理。
+
+## 引用文档模式
+
+`activityType` 传入 `MessageContentType.ReferenceDocument`（`'reference_document'`）或任意非 `'knowledge_rag'` 的值，`content` 传入文档对象数组。
+
+标题自动显示文档数量，始终展示文档图标，`status` 不影响标题和图标。
+
+```vue
+<template>
+  <ActivityMessage
+    v-model:collapsed="collapsed"
+    :content="docs"
+    status="complete"
+    :activity-type="MessageContentType.ReferenceDocument"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ActivityMessage, MessageContentType, MessageStatus } from '@blueking/chat-x';
+
+  const collapsed = ref(false);
+
+  const docs = [
+    {
+      name: 'Vue 3 组合式 API 指南',
+      url: 'https://cn.vuejs.org/guide/extras/composition-api-faq.html',
+      originFile: 'composition-api.md',
+    },
+    { name: 'TypeScript 高级类型手册', url: 'https://www.typescriptlang.org/docs/', originFile: 'ts-advanced.pdf' },
+    { name: '蓝鲸前端开发规范 v2.0', url: 'https://example.com/bk-standard', originFile: 'bk-standard.docx' },
+  ];
+</script>
+```
+
+**渲染效果**
+
+## 知识检索模式
+
+`activityType` 设为 `MessageContentType.KnowledgeRag`（`'knowledge_rag'`），`content` 传入包含 `content`（检索摘要）和 `referenceDocument`（引用文档列表）的对象。
+
+标题和图标随 `status` 动态变化：
+
+| `status`                | 图标     | 标题     |
+| ----------------------- | -------- | -------- |
+| `pending` / `streaming` | Loading  | 检索中   |
+| 其他（`complete` 等）   | 文档图标 | 检索完成 |
+
+```vue
+<template>
+  <ActivityMessage
+    v-model:collapsed="collapsed"
+    :content="ragContent"
+    :status="status"
+    :activity-type="MessageContentType.KnowledgeRag"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ActivityMessage, MessageContentType, MessageStatus } from '@blueking/chat-x';
+
+  const collapsed = ref(false);
+  const status = ref(MessageStatus.Complete);
+
+  const ragContent = {
+    // 检索摘要（支持 Markdown）
+    content: '根据知识库检索，Vue 3 引入了 Composition API...',
+    // 引用文档列表
+    referenceDocument: [
+      { name: '知识库文档：Composition API 详解', url: 'https://example.com/kb1', originFile: 'kb1.md' },
+    ],
+  };
+</script>
+```
+
+**渲染效果（检索完成 + 单引用）**
+
+**渲染效果（检索完成 + 多引用 + Markdown 摘要）**
+
+## 状态变化（知识检索模式）
+
+`knowledge_rag` 模式下，`status` 决定图标和标题文案：
+
+**检索中（`pending`）**
+
+**检索中（`streaming`）**
+
+**检索完成（`complete`）**
+
+> **引用文档模式**不受 `status` 影响，始终显示文档图标和文档数量，不会出现 Loading 动画。
+
+## 折叠/展开
+
+通过 `v-model:collapsed` 控制内容区的折叠状态，点击整个标题栏均可切换。默认为 `false`（展开）。
+
+```vue
+<template>
+  <!-- 默认展开 -->
+  <ActivityMessage
+    v-model:collapsed="collapsed"
+    :content="docs"
+    status="complete"
+    activity-type="reference_document"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ActivityMessage } from '@blueking/chat-x';
+
+  const collapsed = ref(false); // false = 展开，true = 折叠
+  const docs = [{ name: '参考文档', url: 'https://example.com/doc', originFile: 'doc.pdf' }];
+</script>
+```
+
+**渲染效果（展开状态）**
+
+**渲染效果（折叠状态）**
+
+## FlowAgent 执行情况模式
+
+`activityType` 设为 `MessageContentType.FlowAgent`（`'flow-agent'`），`content` 传入 `BkFlowMessageContent` 对象。用于展示蓝鲸标准运维（BkFlow）任务的执行状态、节点列表和统计信息。
+
+### 核心交互
+
+- **标题栏**：显示「执行情况」+ 各状态计数（执行中 / 成功 / 失败 / 挂起），颜色区分
+- **任务组**：可折叠/展开的任务行，带状态图标和总耗时
+- **节点列表**：每个节点显示状态圆点、名称和耗时；hover 时出现「详情」按钮
+- **节点详情**：点击「详情」按钮会通过 `useCustomTabConsumer` 在 `ChatContainer` 侧边栏新增自定义 Tab，展示节点配置（基础信息、输入参数、输出参数）
+
+### 内部渲染结构
+
+```
+FlowAgentContent（activityType = 'flow-agent'）
+├── ActivityLayout（公共折叠布局容器）
+│   └── #title
+│       ├── Loading / ArrowIcon（随 status 切换）
+│       └── 执行情况：执行中 N / 成功 N / 失败 N / 挂起 N
+└── #default
+    └── TaskGroup
+        ├── TaskHeader（可折叠/展开）
+        │   ├── 状态图标（running=Loading / success / failed / suspended）
+        │   ├── task_name（HighlightKeyword 支持搜索高亮）
+        │   └── 总耗时
+        └── NodeList
+            └── NodeItem × N
+                ├── 状态圆点（颜色对应状态）
+                ├── node.name（HighlightKeyword 支持搜索高亮）
+                ├── node.elapsed_time
+                └── 详情按钮（hover 显示）→ 打开自定义 Tab
+```
+
+### 用法示例
+
+```vue
+<template>
+  <ActivityMessage
+    v-model:collapsed="collapsed"
+    :content="flowContent"
+    :status="status"
+    :activity-type="MessageContentType.FlowAgent"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ActivityMessage, MessageContentType, MessageStatus } from '@blueking/chat-x';
+  import type { BkFlowMessageContent } from '@blueking/chat-x';
+
+  const collapsed = ref(false);
+  const status = ref(MessageStatus.Complete);
+
+  const flowContent: BkFlowMessageContent = {
+    task_id: 100,
+    task_name: '数据清洗流程',
+    task_state: 'FINISHED',
+    task_outputs: [],
+    statistics: {
+      total: 3,
+      state_counts: { FINISHED: 2, FAILED: 1 },
+    },
+    nodes: {
+      node1: {
+        id: 'node1',
+        name: '数据拉取',
+        state: 'FINISHED',
+        elapsed_time: 12,
+        start_time: '2025-01-01 10:00:00',
+        finish_time: '2025-01-01 10:00:12',
+        loop: 1,
+        retry: 0,
+        skip: false,
+        type: 'ServiceActivity',
+      },
+      node2: {
+        id: 'node2',
+        name: '数据转换',
+        state: 'FINISHED',
+        elapsed_time: 45,
+        start_time: '2025-01-01 10:00:12',
+        finish_time: '2025-01-01 10:00:57',
+        loop: 1,
+        retry: 0,
+        skip: false,
+        type: 'ServiceActivity',
+      },
+      node3: {
+        id: 'node3',
+        name: '结果写入',
+        state: 'FAILED',
+        elapsed_time: 3,
+        start_time: '2025-01-01 10:00:57',
+        finish_time: '2025-01-01 10:01:00',
+        loop: 1,
+        retry: 0,
+        skip: false,
+        type: 'ServiceActivity',
+      },
+    },
+  };
+</script>
+```
+
+### 在 MessageContainer 中自动渲染
+
+```typescript
+const messages = [
+  {
+    id: '3',
+    role: 'activity',
+    activityType: MessageContentType.FlowAgent, // 'flow-agent'
+    status: MessageStatus.Streaming,
+    content: {
+      task_id: 100,
+      task_name: '数据清洗流程',
+      task_state: 'RUNNING',
+      task_outputs: [],
+      statistics: { total: 3, state_counts: { RUNNING: 1, FINISHED: 2 } },
+      nodes: {
+        /* ... */
+      },
+    },
+  },
+];
+```
+
+### 节点状态映射
+
+组件内部将 BkFlow 原始状态归并为四种显示状态：
+
+| 归并状态    | 原始状态                                                                            | 颜色    |
+| ----------- | ----------------------------------------------------------------------------------- | ------- |
+| `running`   | CREATED / LOOP_READY / READY / RUNNING / BLOCKED / ROLLING_BACK / ROLL_BACK_SUCCESS | #3A84FF |
+| `success`   | FINISHED                                                                            | #18B456 |
+| `failed`    | FAILED / REVOKED / ROLL_BACK_FAILED                                                 | #EA3636 |
+| `suspended` | SUSPENDED                                                                           | #F59500 |
+
+### 节点详情 Tab
+
+点击节点的「详情」按钮，内部调用 `useCustomTabConsumer().addCustomTab()` 在 `ChatContainer` 侧边栏新开一个 Tab，渲染 `FlowAgentNodeDetail` 组件，该组件提供：
+
+- **节点配置** Tab：基础信息表单（流程模板、节点名称、步骤名称、失败处理、超时控制）+ 输入参数表 + 输出参数表
+- **节点输出** Tab：结构化输出参数表
+- **骨架屏**：`loading` 为 `true` 时展示骨架屏占位
+
+### 相关类型定义
+
+```typescript
+import { MessageContentType, type BkFlowMessageContent, type BkFlowNode } from '@blueking/chat-x';
+
+type BkFlowMessageContent = {
+  nodes: Record<string, BkFlowNode>;
+  statistics: { state_counts: Record<string, number>; total: number };
+  task_id: number;
+  task_name: string;
+  task_outputs: unknown[];
+  task_state: string;
+};
+
+type BkFlowNode = {
+  elapsed_time: number;
+  finish_time: string;
+  id: string;
+  loop: number;
+  name: string;
+  retry: number;
+  skip: boolean;
+  start_time: string;
+  state: string;
+  type: string;
+};
+
+enum MessageContentType {
+  FlowAgent = 'flow-agent',
+  KnowledgeRag = 'knowledge-rag',
+  ReferenceDocument = 'reference-document',
+  // ...
+}
+```
+
+## 在 MessageContainer 中使用
+
+`ActivityMessage` 通常不需要单独使用，`MessageContainer` 会对 `role: 'activity'` 的消息自动渲染：
+
+```vue
+<template>
+  <MessageContainer :messages="messages" />
+</template>
+
+<script setup lang="ts">
+  import { MessageContainer, MessageContentType, MessageStatus } from '@blueking/chat-x';
+
+  const messages = [
+    // 知识检索消息
+    {
+      id: '1',
+      role: 'activity',
+      activityType: MessageContentType.KnowledgeRag, // 'knowledge_rag'
+      status: MessageStatus.Complete,
+      content: {
+        content: '根据知识库检索到以下相关信息...',
+        referenceDocument: [{ name: '文档A', url: 'https://example.com/a', originFile: 'a.md' }],
+      },
+    },
+    // 引用文档消息
+    {
+      id: '2',
+      role: 'activity',
+      activityType: MessageContentType.ReferenceDocument, // 'reference_document'
+      status: MessageStatus.Complete,
+      content: [
+        { name: '参考文档1', url: 'https://example.com/doc1', originFile: 'doc1.pdf' },
+        { name: '参考文档2', url: 'https://example.com/doc2', originFile: 'doc2.pdf' },
+      ],
+    },
+  ];
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型                                                                        | 默认值 | 说明                                                      |
+| ------------ | --------------------------------------------------------------------------- | ------ | --------------------------------------------------------- |
+| content      | `ReferenceDocumentContent[] \| KnowledgeRagContent \| BkFlowMessageContent` | -      | 内容数据，格式随 `activityType` 不同                      |
+| activityType | `'knowledge_rag' \| 'flow-agent' \| 'reference_document' \| string`         | -      | 活动类型，决定渲染模式（知识检索 / FlowAgent / 引用文档） |
+| status       | `MessageStatus`                                                             | -      | 消息状态，仅在 `knowledge_rag` 模式下影响标题和图标       |
+| id           | `string \| number`                                                          | -      | 消息 ID                                                   |
+| messageId    | `string \| number`                                                          | -      | 消息唯一标识                                              |
+
+### v-model
+
+| 属性名    | 类型      | 默认值  | 说明                        |
+| --------- | --------- | ------- | --------------------------- |
+| collapsed | `boolean` | `false` | 内容折叠状态，`true` 为折叠 |
+
+## 类型定义
+
+```typescript
+import { MessageContentType } from '@blueking/chat-x';
+
+// 引用文档条目
+type ReferenceDocumentContent = {
+  name: string; // 文档名称（显示文本）
+  url: string; // 文档访问链接
+  originFile: string; // 原始文件名
+};
+
+// 知识检索内容（knowledge_rag 模式）
+interface KnowledgeRagContent {
+  content: string; // 检索摘要，支持 Markdown
+  referenceDocument: ReferenceDocumentContent[]; // 引用文档列表
+}
+
+// activityType 枚举值
+enum MessageContentType {
+  FlowAgent = 'flow-agent',
+  KnowledgeRag = 'knowledge-rag',
+  ReferenceDocument = 'reference-document',
+  // ...
+}
+```
+
+## 使用场景
+
+- **知识检索过程**：以 `knowledge_rag` 模式展示 RAG 检索全过程，从"检索中"到"检索完成"的状态流转
+- **参考资料引用**：以 `reference_document` 模式展示 AI 回复所引用的参考文档列表
+- **FlowAgent 执行监控**：以 `flow-agent` 模式展示 BkFlow 流程执行状态、节点列表和详情
+- **流式场景**：`pending` → `streaming` → `complete` 状态变化配合流式响应实时更新
+- **自动渲染**：通过 `MessageContainer` 或 `MessageRender` 自动处理 `role: 'activity'` 消息，无需手动引入
+
+## 关联组件
+
+- [MessageRender](./message-render.md) — activity 角色由其实例化
+- [FlowMessage](./flow-message.md) — 独立流程消息与 FlowAgent 模式场景相近
+- [AssistantMessage](./assistant-message.md) — 常与助手主回复配合出现

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

@@ -0,0 +1,227 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+AiImage 负责缩略图展示，并处理加载中、失败重试与懒加载；无 ImagePreviewGroup 上下文时可内嵌 ImagePreview 做全屏预览。 在 Group 内通过 inject 注册子图，点击时参与多图集合预览；支持自定义下载与 preview 事件。 与 ImagePreview、ImagePreviewGroup 共同构成对话内图片展示与预览链路。
+
+### 关联组件
+- **image-preview** — 独立模式下内嵌全屏预览，单图预览入口
+- **image-preview-group** — 组内注册子图并统一打开多图预览
+
+---
+<!-- FULL DOC -->
+
+# AiImage 图片展示
+
+> **层级**：原子组件 · **功能域**：文件与图片
+
+图片展示组件，支持加载状态、加载失败重试、懒加载、点击预览等功能。可独立使用（单图预览），也可配合 `ImagePreviewGroup` 实现多图预览。
+
+## 组件结构
+
+```
+.ai-image（display: inline-block，border-radius: 4px）
+├── <img>（v-if status !== 'error' && actualSrc，object-fit: cover）
+├── .ai-image-error（v-if status === 'error'）
+│     └── ImageErrorIcon（24×24，color: #c4c6cc）
+├── .ai-image-error-overlay（v-if status === 'error'，hover 时显示）
+│     ├── ReloadIcon（16×16）
+│     └── <span>"重新加载"</span>
+├── <slot />
+└── ImagePreview（v-if !groupContext && preview && previewVisible）
+      独立模式下的内置全屏预览
+```
+
+## 基础用法
+
+```vue
+<template>
+  <AiImage
+    src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=300&fit=crop"
+    :width="200"
+    :height="150"
+    alt="风景图"
+    @load="handleLoad"
+    @error="handleError"
+    @preview="handlePreview"
+  />
+</template>
+
+<script setup lang="ts">
+  import { AiImage } from '@blueking/chat-x';
+
+  const handleLoad = (ev: Event) => {
+    console.log('图片加载成功', ev);
+  };
+
+  const handleError = (ev: Event) => {
+    console.log('图片加载失败', ev);
+  };
+
+  const handlePreview = () => {
+    console.log('触发预览');
+  };
+</script>
+```
+
+## 加载失败与重新加载
+
+当图片加载失败时，显示错误占位图标，鼠标悬停后出现"重新加载"遮罩，点击可重新加载（内部通过追加时间戳参数实现缓存破坏）：
+
+```vue
+<template>
+  <AiImage
+    src="https://invalid-url.example.com/not-exist.png"
+    :width="200"
+    :height="150"
+  />
+</template>
+```
+
+## 禁用预览
+
+将 `preview` 设为 `false` 可禁用点击预览功能，此时图片不显示 `zoom-in` 光标：
+
+```vue
+<template>
+  <AiImage
+    src="https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=300&fit=crop"
+    :width="200"
+    :height="150"
+    :preview="false"
+  />
+</template>
+```
+
+## 预览属性配置
+
+通过 `previewProps` 可为预览弹窗配置不同的图片源（如高清原图）、名称、尺寸信息等：
+
+```vue
+<template>
+  <AiImage
+    src="https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=400&h=300&fit=crop"
+    :width="200"
+    :height="150"
+    :preview-props="{
+      src: 'https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=1920',
+      name: '森林.jpg',
+      width: 1920,
+      resolution: '1920×1080',
+    }"
+    :show-info="true"
+  />
+</template>
+```
+
+## 多图预览（配合 ImagePreviewGroup）
+
+将多个 `AiImage` 放在 `ImagePreviewGroup` 中，点击任意图片会打开多图预览模式，支持左右切换：
+
+```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>
+```
+
+## 自定义下载
+
+通过 `onDownload` 自定义下载行为（例如调用后端接口），不传时使用默认的 `<a>` 标签下载：
+
+```vue
+<template>
+  <AiImage
+    src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=300&fit=crop"
+    :width="200"
+    :height="150"
+    :on-download="handleDownload"
+  />
+</template>
+
+<script setup lang="ts">
+  import { AiImage } from '@blueking/chat-x';
+
+  const handleDownload = (url: string) => {
+    console.log('自定义下载:', url);
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型                    | 默认值  | 说明                                                            |
+| ------------ | ----------------------- | ------- | --------------------------------------------------------------- |
+| src          | `string`                | —       | **必填**，图片地址                                              |
+| alt          | `string`                | `''`    | 图片 alt 属性                                                   |
+| width        | `number \| string`      | —       | 容器宽度，数字时单位为 px                                       |
+| height       | `number \| string`      | —       | 容器高度，数字时单位为 px                                       |
+| lazy         | `boolean`               | `false` | 是否懒加载（IntersectionObserver，rootMargin: 200px）           |
+| preview      | `boolean`               | `true`  | 是否启用点击预览；为 `true` 且图片加载成功时显示 `zoom-in` 光标 |
+| previewProps | `ImagePreviewConfig`    | —       | 预览弹窗配置（可指定高清源、名称、尺寸等）                      |
+| showInfo     | `boolean`               | `false` | 预览工具栏是否显示图片尺寸信息                                  |
+| onDownload   | `(url: string) => void` | —       | 自定义下载回调；不传时使用默认 `<a>` 标签下载                   |
+
+### Events
+
+| 事件名  | 参数          | 说明               |
+| ------- | ------------- | ------------------ |
+| load    | `(ev: Event)` | 图片加载成功时触发 |
+| error   | `(ev: Event)` | 图片加载失败时触发 |
+| preview | —             | 点击触发预览时触发 |
+
+### Slots
+
+| 插槽名  | 说明                                            |
+| ------- | ----------------------------------------------- |
+| default | 覆盖在图片上方的自定义内容                      |
+| extra   | 预览工具栏的额外操作区域（透传给 ImagePreview） |
+
+### Expose
+
+| 属性名         | 类型           | 说明                             |
+| -------------- | -------------- | -------------------------------- |
+| previewVisible | `Ref<boolean>` | 当前预览弹窗是否可见（独立模式） |
+
+## 类型定义
+
+```typescript
+interface ImagePreviewConfig {
+  src?: string;
+  name?: string;
+  width?: number;
+  height?: number;
+  resolution?: string;
+  downloadUrl?: string;
+}
+```
+
+## 使用场景
+
+- AI 对话中的图片消息展示
+- 需要点击放大查看的缩略图
+- 多图浏览场景（配合 `ImagePreviewGroup`）
+- 懒加载长列表中的图片
+
+## 关联组件
+
+- [ImagePreview](../molecular/image-preview.md) — 独立模式下的全屏预览
+- [ImagePreviewGroup](../molecular/image-preview-group.md) — 多图注册与预览上下文