@blueking/chat-x 0.0.5 → 0.0.6

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

@@ -0,0 +1,305 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+FlowMessage 用于展示 BkFlow/流水线类流程的执行统计、节点分组与节点详情（含 Tab 详情）。消息类型为 flow，需在业务布局中显式嵌入； 标准 MessageRender 角色分发未包含 flow。与 Activity 的 FlowAgent 模式同属流程可视化但组件与数据模型不同。
+
+### 关联组件
+- **activity-message** — Activity 的 flow-agent 模式同样展示流程执行，场景互补
+- **message-container** — 嵌入对话列表时需与消息容器等配合布局
+- **execution-summary** — 对话级执行摘要与单条流程消息可共同构成执行态 UI
+
+---
+<!-- FULL DOC -->
+
+# FlowMessage 流程消息
+
+> **层级**：分子组件 · **功能域**：消息展示
+
+流程消息组件，用于展示流程编排（如标准运维 / CI/CD 流水线）的执行状态和节点详情。包含执行统计摘要、节点组列表、节点详情面板，提供完整的流程执行可视化能力。
+
+## 组件结构
+
+```
+flow-message
+├── flow-message__stats（执行情况摘要栏）
+│   ├── 执行中：N    （蓝色）
+│   ├── 成功：N      （绿色）
+│   ├── 失败：N      （红色）
+│   └── 挂起：N      （橙色）
+├── flow-message__groups
+│   └── FlowNodeGroup × N（可折叠的节点组）
+│       ├── 组标题栏（折叠图标 + 状态图标 + 名称 + 耗时）
+│       └── FlowNodeItem × N（节点列表）
+│           ├── 状态图标 + 名称 + 耗时
+│           └── 详情入口（点击 → Teleport FlowDetail）
+├── flow-message__extra（额外文本，可选）
+└── <Teleport>
+    └── FlowDetail（节点详情面板）
+        ├── 基础信息 Tab
+        └── 输入/输出参数 Tab
+```
+
+## 基础用法
+
+```vue
+<template>
+  <FlowMessage :content="content" />
+</template>
+
+<script setup lang="ts">
+  const content = {
+    stats: { running: 1, success: 3, failed: 0, pending: 2 },
+    groups: [
+      {
+        id: 'group-1',
+        name: '部署阶段',
+        status: 'running',
+        duration: 120,
+        nodes: [
+          { id: 'node-1', name: '代码拉取', status: 'success', duration: 30 },
+          { id: 'node-2', name: '编译构建', status: 'success', duration: 60 },
+          { id: 'node-3', name: '部署上线', status: 'running', duration: 30 },
+        ],
+      },
+    ],
+  };
+</script>
+```
+
+**渲染效果**
+
+## 执行统计
+
+顶部摘要栏展示四种状态的节点数量，数量 ≥ 100 时显示为 `99+`：
+
+| 状态   | 颜色 | 说明            |
+| ------ | ---- | --------------- |
+| 执行中 | 蓝色 | `stats.running` |
+| 成功   | 绿色 | `stats.success` |
+| 失败   | 红色 | `stats.failed`  |
+| 挂起   | 橙色 | `stats.pending` |
+
+## 带额外内容
+
+`extraContent` 以灰色背景文本块显示在节点组下方，适合展示执行总结或错误提示：
+
+```vue
+<script setup lang="ts">
+  const content = {
+    stats: { running: 0, success: 5, failed: 1, pending: 0 },
+    groups: [
+      {
+        id: 'group-1',
+        name: '测试阶段',
+        status: 'failed',
+        nodes: [
+          { id: 'node-1', name: '单元测试', status: 'success', duration: 45 },
+          { id: 'node-2', name: '集成测试', status: 'failed', duration: 120 },
+        ],
+      },
+    ],
+    extraContent: '流程执行失败，请检查集成测试节点的错误日志。',
+  };
+</script>
+```
+
+**渲染效果**
+
+## 节点详情
+
+节点数据包含 `detail` 字段时，点击节点右侧入口可打开详情面板。详情面板通过 `<Teleport>` 渲染到 `ChatContainer` 的侧边栏插槽区域（`#ai-blueking-message-slot`），包含：
+
+- **基础信息**：流程模板、节点名称、步骤名称、执行方案、失败处理、超时控制等
+- **输入参数**：`name` + `value` 键值对列表
+- **输出参数**：`name` + `description` + `key` 列表
+
+```vue
+<script setup lang="ts">
+  const content = {
+    stats: { running: 0, success: 1, failed: 0, pending: 0 },
+    groups: [
+      {
+        id: 'group-1',
+        name: '部署阶段',
+        status: 'success',
+        duration: 90,
+        nodes: [
+          {
+            id: 'node-1',
+            name: '部署上线',
+            status: 'success',
+            duration: 90,
+            detail: {
+              baseInfo: {
+                flowTemplate: '标准部署流程',
+                nodeName: '部署上线',
+                stepName: '执行部署',
+                executePlan: '蓝绿部署',
+                isOptional: false,
+                failureHandler: '自动回滚',
+                timeoutControl: '600s',
+                useLatestVersion: true,
+              },
+              inputParams: [
+                { name: 'env', value: 'production' },
+                { name: 'version', value: 'v1.2.3' },
+              ],
+              outputParams: [{ name: '部署结果', description: '部署是否成功', key: 'deploy_result' }],
+            },
+          },
+        ],
+      },
+    ],
+  };
+</script>
+```
+
+**渲染效果**
+
+## 节点状态图标
+
+每个节点根据 `status` 渲染不同的状态图标：
+
+| 状态      | 图标     | 颜色 |
+| --------- | -------- | ---- |
+| `running` | 旋转加载 | 蓝色 |
+| `success` | 对勾     | 绿色 |
+| `failed`  | 叉号     | 红色 |
+| `pending` | 时钟     | 橙色 |
+
+## 在 MessageContainer 中的使用
+
+`FlowMessage` 由 `MessageRender` 根据 `role: 'flow'` 自动调度渲染，通常不需要手动引入：
+
+```vue
+<script setup lang="ts">
+  import { MessageContainer, type Message } from '@blueking/chat-x';
+
+  const messages: Message[] = [
+    {
+      id: '1',
+      messageId: '1',
+      role: 'flow',
+      status: 'complete',
+      content: {
+        stats: { running: 0, success: 2, failed: 0, pending: 0 },
+        groups: [
+          {
+            id: 'g1',
+            name: '构建阶段',
+            status: 'success',
+            duration: 180,
+            nodes: [
+              { id: 'n1', name: '代码编译', status: 'success', duration: 120 },
+              { id: 'n2', name: '单元测试', status: 'success', duration: 60 },
+            ],
+          },
+        ],
+      },
+    },
+  ];
+</script>
+```
+
+## API
+
+### Props
+
+组件 Props 继承自 `Partial<FlowMessage>` 类型：
+
+| 属性名    | 类型                 | 说明         |
+| --------- | -------------------- | ------------ |
+| content   | `FlowMessageContent` | 流程消息内容 |
+| status    | `MessageStatus`      | 消息状态     |
+| id        | `string`             | 客户端 ID    |
+| messageId | `number \| string`   | 消息唯一标识 |
+
+## 类型定义
+
+```typescript
+// 流程消息内容
+interface FlowMessageContent {
+  stats: FlowExecutionStats;
+  groups: FlowNodeGroup[];
+  extraContent?: string;
+}
+
+// 执行统计
+interface FlowExecutionStats {
+  running: number;
+  success: number;
+  failed: number;
+  pending: number;
+}
+
+// 节点组
+interface FlowNodeGroup {
+  id: string;
+  name: string;
+  status: FlowNodeStatus;
+  duration?: number;
+  nodes: FlowNode[];
+}
+
+// 节点
+interface FlowNode {
+  id: string;
+  name: string;
+  status: FlowNodeStatus;
+  duration?: number;
+  detail?: FlowNodeDetail;
+}
+
+// 节点状态
+enum FlowNodeStatus {
+  Running = 'running',
+  Success = 'success',
+  Failed = 'failed',
+  Pending = 'pending',
+}
+
+// 节点详情
+interface FlowNodeDetail {
+  baseInfo: FlowNodeBaseInfo;
+  inputParams: FlowNodeParam[];
+  outputParams: FlowNodeOutput[];
+}
+
+// 节点基础信息
+interface FlowNodeBaseInfo {
+  flowTemplate: string;
+  nodeName: string;
+  stepName: string;
+  executePlan: string;
+  isOptional: boolean;
+  failureHandler: string;
+  timeoutControl: string;
+  useLatestVersion: boolean;
+}
+
+// 节点参数
+interface FlowNodeParam {
+  name: string;
+  value: string;
+}
+
+// 节点输出
+interface FlowNodeOutput {
+  name: string;
+  description: string;
+  key: string;
+}
+```
+
+## 使用场景
+
+- 展示标准运维（SOPS）流程的执行过程和状态
+- 展示 CI/CD 流水线的节点执行情况
+- 可视化任务编排的执行进度和结果
+- 查看流程节点的详细配置、输入参数和输出参数
+
+## 关联组件
+
+- [ActivityMessage](./activity-message.md) — FlowAgent 活动消息与流程编排展示场景相近
+- [MessageContainer](./message-container.md) — 嵌入消息列表时的容器
+- [ExecutionSummary](./execution-summary.md) — 对话级执行摘要

package/dist/mcp/generated/docs/highlight-keyword.md

@@ -0,0 +1,144 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+HighlightKeyword 为函数式组件，从 inject 读取关键词并将匹配片段包在带样式 span 中，用于对话内搜索与列表过滤高亮。 ToolcallRender、DescPanel、FlowAgent 等场景组合使用。
+
+### 关联组件
+- **toolcall-render** — 工具调用标题与状态文案高亮
+- **desc-panel** — 工具详情键值与描述文本高亮
+- **execution-summary** — 执行摘要搜索过滤与列表高亮
+
+---
+<!-- FULL DOC -->
+
+# HighlightKeyword 关键词高亮
+
+> **层级**：原子组件 · **功能域**：辅助组件
+
+函数式组件，用于在文本中高亮匹配的搜索关键词。通过 `useKeywordInject` 从上层注入关键词，自动将匹配部分包裹在带高亮样式的 `<span>` 中。
+
+主要配合 `ExecutionSummary` 的搜索功能使用，实现搜索结果的视觉高亮。
+
+## 工作原理
+
+```
+props.text + inject(keyword)
+        │
+        ├── keyword 为空 → 直接渲染原文本
+        │
+        └── keyword 非空
+            ├── 正则 split 文本为 parts[]
+            ├── parts.length === 1 → 无匹配，渲染原文本
+            └── parts.length > 1 → 匹配部分用 <span class="highlight"> 包裹
+```
+
+组件使用 `defineComponent` + `h()` 渲染函数实现，不依赖模板。
+
+## 基础用法
+
+```vue
+<template>
+  <HighlightKeyword :text="text" />
+</template>
+
+<script setup lang="ts">
+  import { HighlightKeyword } from '@blueking/chat-x';
+
+  const text = '这是一段包含 Vue 3 Composition API 的示例文本';
+</script>
+```
+
+> **注意**：关键词通过 `useKeywordProvider` / `useKeywordInject`（`provide/inject`）注入，不通过 props 传入。上层需先调用 `useKeywordProvider()` 设置关键词。
+
+**渲染效果**（在输入框中输入关键词，观察文本高亮变化）
+
+## 关键词高亮示例
+
+预设关键词为 `API`，文本中所有匹配部分会以高亮背景显示：
+
+## 与 ExecutionSummary 配合
+
+`ExecutionSummary` 内部通过 `useKeywordProvider` 提供搜索关键词，后代组件中的 `HighlightKeyword` 自动响应：
+
+```
+ExecutionSummary
+├── useKeywordProvider(keyword)  ← Input 绑定
+└── MessageRender
+    └── AssistantMessage
+        └── ToolcallRender
+            └── HighlightKeyword(:text)  ← inject(keyword)
+```
+
+## 配套 Composables
+
+### useKeywordProvider
+
+在上层组件中创建关键词并 `provide`，后代组件通过 `useKeywordInject` 消费：
+
+```typescript
+import { useKeywordProvider } from '@blueking/chat-x';
+
+const { keyword } = useKeywordProvider();
+keyword.value = '搜索词';
+```
+
+### useKeywordInject
+
+在后代组件中注入关键词，返回 `ComputedRef<string> | undefined`：
+
+```typescript
+import { useKeywordInject } from '@blueking/chat-x';
+
+const keyword = useKeywordInject();
+console.log(keyword?.value); // 当前搜索关键词
+```
+
+### useKeywordMatch
+
+用于判断组件的可搜索文本是否与当前关键词匹配。内部调用 `useKeywordInject` 获取关键词，根据传入的文本提取函数判断是否命中：
+
+```typescript
+import { useKeywordMatch } from '@blueking/chat-x';
+
+const { keywordMatched } = useKeywordMatch(() => [props.title, props.description, props.content]);
+
+// keywordMatched.value === true 表示命中搜索
+// keywordMatched.value === false 表示未命中（可据此隐藏组件）
+// keyword 为空时始终返回 true
+```
+
+`useKeywordMatch` 的典型用途是在 `ExecutionSummary` 的搜索过滤中，让组件自行判断是否匹配搜索词，与 `HighlightKeyword` 配合实现搜索 + 高亮。
+
+## API
+
+### Props
+
+| 属性名 | 类型     | 必填 | 说明       |
+| ------ | -------- | ---- | ---------- |
+| text   | `string` | ✓    | 待高亮文本 |
+
+### 依赖注入
+
+| 注入项  | 提供方               | 说明                   |
+| ------- | -------------------- | ---------------------- |
+| keyword | `useKeywordProvider` | 搜索关键词，响应式更新 |
+
+### 配套 Composables
+
+| 函数名               | 参数                                            | 返回值                                     | 说明                                          |
+| -------------------- | ----------------------------------------------- | ------------------------------------------ | --------------------------------------------- |
+| `useKeywordProvider` | —                                               | `{ keyword: ShallowRef<string> }`          | 创建并 `provide` 关键词，用于上层组件         |
+| `useKeywordInject`   | —                                               | `ComputedRef<string> \| undefined`         | 注入关键词，用于后代组件                      |
+| `useKeywordMatch`    | `getSearchTexts: () => (string \| undefined)[]` | `{ keywordMatched: ComputedRef<boolean> }` | 判断组件文本是否匹配关键词，空关键词返回 true |
+
+### CSS 类名
+
+| 类名                    | 说明                                |
+| ----------------------- | ----------------------------------- |
+| `.ai-highlight-keyword` | 匹配文本的高亮样式（背景色 + 圆角） |
+
+## 关联组件
+
+- [ToolcallRender](../molecular/toolcall-render.md) — 工具调用头部高亮
+- [DescPanel](./desc-panel.md) — 详情面板键值高亮
+- [ExecutionSummary](../molecular/execution-summary.md) — 执行摘要搜索

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

@@ -0,0 +1,178 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ImageContent 在 Markdown 解析到图片 token 时渲染，对流式拼接中的 URL 做防抖与预加载，并用模块级缓存避免重复闪烁。 三态展示加载中、成功与失败，通常由 MarkdownContent 自动挂载而非业务直接引用。
+
+### 关联组件
+- **markdown-content** — 解析图片 token 后挂载本组件
+
+---
+<!-- FULL DOC -->
+
+# ImageContent 图片渲染
+
+> **层级**：原子组件 · **功能域**：文件与图片
+
+Markdown Token 层的图片渲染原子组件，被 `MarkdownContent` 在解析到图片 token 时自动调用，通常无需手动引入。
+
+核心能力：**流式 URL 防闪烁**（debounce 稳定判断 + throttle 预加载）、**全局缓存**（模块级 `Set` 跨实例共享）、**三态渲染**（加载中 / 成功 / 失败）。
+
+## 组件结构
+
+```
+span.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](./markdown-content.md) — 图片 token 渲染入口