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

package/skills/blueking-chat-x/references/components/flow-agent-node-detail.md

@@ -0,0 +1,236 @@
+# FlowAgentNodeDetail FlowAgent 节点详情
+
+> 能力域：Agent 能力 ｜ 导入：`import { FlowAgentNodeDetail } from '@blueking/chat-x'` ｜ since 1.0.0
+
+展示 FlowAgent 节点输入、输出、异常、耗时等详情。 源码位置：src/components/chat-content/flow-agent-content/flow-agent-node-detail.vue。
+
+**关联**：flow-agent-content（节点详情入口由 FlowAgentContent 挂载到自定义 Tab）、detail-section（详情页内部分段容器）、simple-table（展示输入参数、插件输出定义与结构化输出）、chat-container（应用层通过 onCustomTabChange 拉取节点详情并回填）
+
+---
+
+# FlowAgentNodeDetail FlowAgent 节点详情
+
+> **能力域**：Agent 能力
+
+`FlowAgentNodeDetail` 用于展示 FlowAgent 单个节点的配置与输出详情。它通常被 `FlowAgentContent` 通过自定义 Tab 挂载到侧栏，应用层再根据 `messageUid`、`task_id`、`node_id` 拉取真实节点详情并回填到 `data`。
+
+组件自身只负责详情展示，不负责接口请求、Tab 生命周期或消息定位逻辑。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/flow-agent-content/flow-agent-node-detail.vue`
+- **能力说明**：展示 FlowAgent 节点输入、输出、异常、耗时等详情。
+
+## 核心能力
+
+- **双 Tab 展示**：内置“节点配置”和“节点输出”两个页签，默认展示“节点配置”
+- **配置详情**：展示流程模板、节点名称、步骤名称、是否可选、失败处理和超时控制
+- **参数表格**：使用 `SimpleTable` 展示输入参数、插件输出定义和结构化输出
+- **加载骨架屏**：`loading` 为 `true` 时展示标题和内容骨架，不渲染真实数据
+- **定位插槽**：提供 `locateButton` 插槽，允许侧栏注入“在对话中定位”等操作按钮
+- **值格式化**：`null` / `undefined` 显示为 `--`，对象值通过 `JSON.stringify` 转为字符串
+
+## 基础用法
+
+```vue
+<template>
+  <FlowAgentNodeDetail
+    :data="nodeDetailData"
+    :loading="false"
+    node_id="n1"
+    node_name="采集主机指标"
+    :task_id="100"
+    task_name="主机巡检流程"
+  >
+    <template #locateButton>
+      <button type="button">定位</button>
+    </template>
+  </FlowAgentNodeDetail>
+</template>
+
+<script setup lang="ts">
+  import FlowAgentNodeDetail from '@blueking/chat-x/src/components/chat-content/flow-agent-content/flow-agent-node-detail.vue';
+  import type { NodeDetailData } from '@blueking/chat-x';
+
+  const nodeDetailData: Partial<NodeDetailData> = {
+    basic_info: {
+      node_name: '采集主机指标',
+      template_name: '主机巡检流程',
+      stage_name: '巡检准备',
+      optional: false,
+      skippable: true,
+      retryable: true,
+      error_ignorable: false,
+      auto_retry: { enable: true, interval: 30, times: 2 },
+      timeout_config: { enable: true, seconds: 300, action: 'forced_fail' },
+    },
+    inputs: {
+      bk_host_id: 10001,
+      collect_items: ['cpu', 'memory', 'disk'],
+    },
+    plugin_output: [
+      {
+        key: '${cpu_usage}',
+        name: 'CPU 使用率',
+        type: 'number',
+        schema: { description: '当前主机 CPU 使用率', enum: [], type: 'number' },
+      },
+    ],
+    outputs: [{ key: 'cpu_usage', preset: false, value: 23.5 }],
+  };
+</script>
+```
+
+**渲染效果**
+
+## 加载态
+
+`loading` 为 `true` 时，组件展示骨架屏，标题中的节点名和内容区均不会读取 `data` 展示。
+
+## 空数据
+
+当输入参数、插件输出定义或结构化输出为空时，对应 `SimpleTable` 渲染 `--` 占位行。
+
+## Tab 内容
+
+| Tab        | 内容                                                         |
+| ---------- | ------------------------------------------------------------ |
+| 节点配置   | 基础信息、失败处理、超时控制、输入参数、插件输出定义         |
+| 节点输出   | 结构化输出，来自 `data.outputs`                              |
+
+`activeTab` 是组件内部状态，不通过 prop 或 expose 暴露。
+
+## 字段展示规则
+
+| 区域         | 数据来源                         | 展示规则                                      |
+| ------------ | -------------------------------- | --------------------------------------------- |
+| 流程模板     | `data.basic_info.template_name`   | 空值显示 `--`                                 |
+| 节点名称     | `data.basic_info.node_name`       | 空值显示 `--`                                 |
+| 步骤名称     | `data.basic_info.stage_name`      | 空值显示 `--`                                 |
+| 是否可选     | `data.basic_info.optional`        | `true` 显示“是”，否则显示“否”                 |
+| 失败处理     | `skippable` / `auto_retry.enable` | 支持“手动跳过”和“自动重试”；均无时显示 `--`  |
+| 超时控制     | `timeout_config`                  | 未启用时显示 `--`；`forced_fail` 显示“强制失败” |
+| 输入参数     | `data.inputs`                     | 对象条目转为 `{ key, value }` 表格            |
+| 插件输出定义 | `data.plugin_output`              | 展示名称、变量说明和 KEY                     |
+| 结构化输出   | `data.outputs`                    | 展示输出 key 与格式化后的 value              |
+
+## 自定义 Tab 联动
+
+`FlowAgentContent` 点击节点“详情”时，会将本组件挂载到自定义 Tab，并先传入 `loading: true` 和节点定位参数：
+
+```typescript
+addCustomTab?.({
+  label: node.name,
+  name: `${task.task_id}|${node.id}|${node.name}`,
+  data: {
+    component: BkFlowNodeDetail,
+    messageUid: props.messageUid,
+    props: {
+      loading: true,
+      node_id: node.id,
+      node_name: node.name,
+      task_id: task.task_id,
+      task_name: task.task_name,
+      data: {},
+    },
+  },
+});
+```
+
+应用层通常在 `ChatContainer` 的 `onCustomTabChange` 中读取这些参数，请求节点详情后返回新的 `props.data` 和 `props.loading`。
+
+## API
+
+### Props
+
+| 属性名    | 类型                       | 必填 | 默认值 | 说明                         |
+| --------- | -------------------------- | ---- | ------ | ---------------------------- |
+| data      | `Partial<NodeDetailData>`  | 是   | —      | 节点详情数据                 |
+| loading   | `boolean`                  | 否   | —      | 是否显示骨架屏               |
+| node_id   | `string`                   | 否   | —      | 节点 ID，来自自定义 Tab 参数 |
+| node_name | `string`                   | 否   | —      | 节点名称                     |
+| task_id   | `number`                   | 否   | —      | 任务 ID                      |
+| task_name | `string`                   | 否   | —      | 任务名称                     |
+
+> Props 类型来自 `CustomBkFlowTabData['props'] & { data: Partial<NodeDetailData> }`。
+
+### Emits
+
+- 无。
+
+### Slots
+
+| 插槽名       | 说明                         |
+| ------------ | ---------------------------- |
+| locateButton | 标题栏右侧操作区，如定位按钮 |
+
+### Expose
+
+- 无。
+
+## 类型定义
+
+```typescript
+export type CustomBkFlowTabData = CustomTabData<{
+  data?: Partial<NodeDetailData>;
+  loading?: boolean;
+  node_id?: string;
+  node_name?: string;
+  task_id?: number;
+  task_name?: string;
+}>;
+
+export interface NodeDetailData {
+  inputs: Record<string, unknown>;
+  node_id: string;
+  task_id: number;
+  basic_info: {
+    auto_retry: {
+      enable: boolean;
+      interval: number;
+      times: number;
+    };
+    error_ignorable: boolean;
+    node_name: string;
+    optional: boolean;
+    retryable: boolean;
+    skippable: boolean;
+    stage_name: string;
+    template_name: string;
+    timeout_config: {
+      action: string;
+      enable: boolean;
+      seconds: number;
+    };
+  };
+  outputs: Array<{
+    key: string;
+    preset: boolean;
+    value: unknown;
+  }>;
+  plugin_output: Array<{
+    key: string;
+    name: string;
+    schema: {
+      description: string;
+      enum: unknown[];
+      properties?: Record<string, unknown>;
+      type: string;
+    };
+    type: string;
+  }>;
+}
+```
+
+## 使用建议
+
+- 优先由 [FlowAgentContent](./flow-agent-content.md) 通过自定义 Tab 挂载，不建议业务组件手动拼装 Tab 生命周期。
+- 接口请求与数据回填应放在应用层 `ChatContainer` 的 `onCustomTabChange` 链路中处理。
+- `data` 可传 `Partial<NodeDetailData>`，但真实展示依赖 `basic_info`、`inputs`、`plugin_output`、`outputs` 等字段；缺字段时对应区域会降级为空表格或 `--`。
+
+## 关联组件
+
+- [FlowAgentContent](./flow-agent-content.md) — 节点详情入口。
+- [DetailSection](./detail-section.md) — 详情分段容器。
+- [SimpleTable](./simple-table.md) — 详情表格。
+- [ChatContainer](../setup/chat-container.md) — 自定义 Tab 数据回填入口。

package/skills/blueking-chat-x/references/components/highlight-keyword.md

@@ -0,0 +1,146 @@
+# HighlightKeyword 关键词高亮
+
+> 能力域：辅助能力 ｜ 导入：`import { HighlightKeyword } from '@blueking/chat-x'` ｜ since 1.0.0
+
+根据注入关键词高亮文本片段。 源码位置：src/components/highlight-keyword/highlight-keyword.ts。
+
+**关联**：toolcall-render（工具调用标题与状态文案高亮）、desc-panel（工具详情键值与描述文本高亮）、execution-summary（执行摘要搜索过滤与列表高亮）
+
+---
+
+# HighlightKeyword 关键词高亮
+## 源码事实
+
+- **源码位置**：`src/components/highlight-keyword/highlight-keyword.ts`
+- **能力域**：辅助能力
+- **能力说明**：根据注入关键词高亮文本片段。
+
+> **能力域**：辅助能力
+
+函数式组件，用于在文本中高亮匹配的搜索关键词。通过 `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](/components/agent/toolcall-render) — 工具调用头部高亮
+- [DescPanel](/components/rendering/desc-panel) — 详情面板键值高亮
+- [ExecutionSummary](/components/agent/execution-summary) — 执行摘要搜索

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 渲染入口