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

package/skills/blueking-chat-x/references/components/delete-tool.md

@@ -0,0 +1,191 @@
+# DeleteTool 删除确认按钮
+
+> 能力域：工具与反馈 ｜ 导入：`import { DeleteTool } from '@blueking/chat-x'` ｜ since 1.0.0
+
+消息删除二次确认工具。 源码位置：src/components/message-tools/delete-tool/delete-tool.vue。
+
+**关联**：tool-btn（删除图标与触发入口）、message-tools（delete 工具 id 时自动采用本组件）
+
+---
+
+# DeleteTool 删除确认按钮
+## 源码事实
+
+- **源码位置**：`src/components/message-tools/delete-tool/delete-tool.vue`
+- **能力域**：工具与反馈
+- **能力说明**：消息删除二次确认工具。
+
+> **能力域**：工具与反馈
+
+删除操作的二次确认组件。点击删除图标后弹出确认弹窗，用户需再次点击"删除"按钮才会触发 `confirm` 事件，防止误删。内部由 `ToolBtn`（触发按钮）+ `Tippy`（确认弹窗）组合实现。
+
+> **提示**：此组件通常**不需要手动使用**，`MessageTools` 在工具列表中检测到 `id === 'delete'` 时会自动使用此组件替换普通 `ToolBtn`。
+
+## 组件结构
+
+```
+Tippy（trigger='click'，interactive，appendTo=body）
+  │
+  ├── ToolBtn（触发按钮，id/name/description/disabled 透传）
+  │
+  └── #content: div.ai-delete-confirm（width: 280px）
+        ├── .ai-delete-confirm__title   "确认删除该回答？"（16px, bold）
+        ├── .ai-delete-confirm__desc    "删除操作无法撤回，请谨慎操作！"
+        └── .ai-delete-confirm__actions（justify-content: flex-end，gap: 8px）
+              ├── Button（theme="danger", size="small"）→ 点击触发 confirm + 关闭弹窗
+              └── Button（size="small"）→ 点击触发 cancel + 关闭弹窗
+
+disabled=true 时：Tippy onShow 返回 false，弹窗不打开
+```
+
+## 基础用法
+
+```vue
+<template>
+  <DeleteTool
+    id="delete"
+    name="删除"
+    description="删除消息"
+    @confirm="handleConfirm"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup lang="ts">
+  import { DeleteTool } from '@blueking/chat-x';
+
+  const handleConfirm = () => {
+    console.log('用户确认删除，执行删除操作');
+  };
+
+  const handleCancel = () => {
+    console.log('用户取消删除');
+  };
+</script>
+```
+
+## 禁用状态
+
+`disabled=true` 时，点击按钮不弹出确认弹窗：
+
+```vue
+<template>
+  <DeleteTool
+    id="delete"
+    name="删除"
+    description="删除消息"
+    :disabled="true"
+    @confirm="handleConfirm"
+  />
+</template>
+```
+
+## 在 MessageTools 中的自动使用
+
+`MessageTools` 在渲染工具列表时，若检测到 `tool.id === 'delete'`，会自动使用 `DeleteTool` 替换普通 `ToolBtn`，无需手动配置：
+
+```vue
+<template>
+  <MessageTools
+    :update-tools="updateTools"
+    :on-action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  // delete 会自动使用 DeleteTool 渲染，点击弹确认框，确认后 onAction 触发
+  const updateTools: IToolBtn[] = [
+    { id: 'like', name: '点赞', description: '点赞' },
+    { id: 'unlike', name: '不满意', description: '不满意' },
+    { id: 'delete', name: '删除', description: '删除消息' },
+  ];
+
+  const handleAction = async (tool: IToolBtn) => {
+    if (tool.id === 'delete') {
+      // 只有用户在弹窗中点击"删除"确认后，才会走到这里
+      console.log('执行删除:', tool.id);
+    }
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型                                                                       | 必填 | 默认值 | 说明                                                                 |
+| ------------ | -------------------------------------------------------------------------- | ---- | ------ | -------------------------------------------------------------------- |
+| id           | `string`                                                                   | 是   | —      | 按钮标识，传 `"delete"` 时显示删除图标                               |
+| name         | `string`                                                                   | 否   | —      | 按钮名称，`id` 无对应图标时作为文本内容渲染                          |
+| description  | `string`                                                                   | 否   | —      | `ToolBtn` 的 tooltip 文本；`disabled=true` 时不显示                  |
+| disabled     | `boolean`                                                                  | 否   | —      | 禁用态；`true` 时点击不弹出确认弹窗，`ToolBtn` 同步禁用              |
+| tippyOptions | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | 否   | —      | 覆盖确认弹窗（`Tippy`）的默认配置；可覆盖 `placement`、`appendTo` 等 |
+
+### Events
+
+| 事件名  | 参数 | 触发时机                           |
+| ------- | ---- | ---------------------------------- |
+| confirm | —    | 用户在确认弹窗点击"删除"按钮后触发 |
+| cancel  | —    | 用户在确认弹窗点击"取消"按钮后触发 |
+
+## 类型定义
+
+```typescript
+import type { IToolBtn } from '@blueking/chat-x';
+import type { TippyOptions } from 'vue-tippy';
+
+export type DeleteToolProps = IToolBtn & {
+  disabled?: boolean;
+  tippyOptions?: Partial<Omit<TippyOptions, 'getReferenceClientRect' | 'triggerTarget'>>;
+};
+```
+
+## 样式说明
+
+确认弹窗（`.ai-delete-confirm`）样式：
+
+```scss
+.ai-delete-confirm {
+  width: 280px;
+  padding: 16px;
+  font-size: 12px;
+  color: #4d4f56;
+  background: #fff;
+  border: 1px solid #dcdee5;
+  box-shadow: 0 2px 6px 0 #0000001a;
+
+  &__title {
+    margin-bottom: 6px;
+    font-size: 16px;
+    font-weight: 600;
+    line-height: 22px;
+    color: #313238;
+  }
+
+  &__desc {
+    margin-bottom: 16px;
+    line-height: 20px;
+  }
+
+  &__actions {
+    display: flex;
+    gap: 8px;
+    justify-content: flex-end;
+  }
+}
+```
+
+## 注意事项
+
+1. **确认才触发**：`confirm` 事件只在用户点击弹窗内"删除"按钮后触发；直接点击 `ToolBtn` 触发器不会触发任何业务事件
+2. **`disabled` 双重保障**：`disabled=true` 时，`ToolBtn` 的 JS 层拦截 click，且 `Tippy` 的 `onShow` 返回 `false`，弹窗不会弹出
+3. **弹窗挂载至 body**：默认 `appendTo: () => document.body`，避免被父容器 `overflow: hidden` 裁剪
+4. **组件卸载自动关闭**：`onUnmounted` 时调用 `hide()` 关闭弹窗，防止组件销毁后弹窗残留
+5. **`MessageTools` 自动处理**：通常不需要直接使用此组件，`MessageTools` 会在 `id === 'delete'` 时自动替换
+
+## 关联组件
+
+- [ToolBtn](/components/feedback/tool-btn) — 触发按钮
+- [MessageTools](/components/feedback/message-tools) — 工具栏中 delete 替换入口

package/skills/blueking-chat-x/references/components/desc-panel.md

@@ -0,0 +1,162 @@
+# DescPanel 描述面板
+
+> 能力域：内容渲染 ｜ 导入：`import { DescPanel } from '@blueking/chat-x'` ｜ since 1.0.0
+
+将文本或 JSON 内容降级为可读描述面板。 源码位置：src/components/tool-call/desc-panel/desc-panel.vue。
+
+**关联**：toolcall-render（工具调用详情中渲染描述与参数）、tool-message（工具返回内容同样由 DescPanel 承载）、highlight-keyword（键值与文本匹配关键词高亮）
+
+---
+
+# DescPanel 描述面板
+## 源码事实
+
+- **源码位置**：`src/components/tool-call/desc-panel/desc-panel.vue`
+- **能力域**：内容渲染
+- **能力说明**：将文本或 JSON 内容降级为可读描述面板。
+
+> **能力域**：内容渲染
+
+工具调用（ToolCall）详情面板的描述区域组件，主要用于 `ToolcallRender` 内部的折叠面板中。
+
+将 `desc` 字符串尝试解析为 JSON，解析成功且结果为对象/数组时以键值对列表渲染，否则作为纯文本展示。
+
+## 组件结构
+
+```
+.ai-toolcall-desc（flex column，padding: 0 16px，max-height: 300px，overflow-y: auto，
+                  font-size: 12px，line-height: 20px，color: #4d4f56，background: #f5f7fa，radius: 2px）
+├── .desc-title（sticky top: 0，flex + gap 4px，padding: 12px 0 4px，加粗，背景同面板）
+│     ├── {{ title }}
+│     └── .desc-copy（v-if desc；CopyIcon 14×14，margin-left: auto，默认 visibility: hidden）
+└── .desc-panel（flex column，gap: 4px，padding-bottom: 12px）
+      ├── [JSON 对象/数组] v-for 逐项渲染 .desc-panel-item
+      │     ├── .desc-label  → HighlightKeyword(key) + 半角冒号
+      │     └── .desc-value → HighlightKeyword(值的文本或 JSON 字符串)，`word-break: break-all`
+      └── [非 JSON / 解析失败] HighlightKeyword(data)，`word-break: break-all`
+```
+
+面板整体限高 **300px**，超出后内部滚动，`.desc-title` 吸顶不动。纵向留白由标题的 `padding-top` 与内容区的 `padding-bottom` 承担（容器自身不设上下 padding），避免标题吸顶时上方留白漏出滚动内容。
+
+> **说明**：键值与纯文本均通过 `HighlightKeyword` 展示，长内容依赖换行与面板宽度展示，**不再**使用 `v-overflow-tips` 悬停气泡。
+
+## 复制原始内容
+
+`desc` 有值时，标题右侧渲染复制按钮（`.desc-copy`），默认 `visibility: hidden`，鼠标移入面板后显示，图标默认 `#979ba5`、hover `#3a84ff`：
+
+```typescript
+// 复制的是原始 desc 字符串，而非解析后的展示内容，便于粘贴后二次使用
+const handleCopy = () => {
+  if (props.desc) {
+    copy(props.desc);
+  }
+};
+```
+
+复制能力来自 [useClipboard](/composables/use-clipboard)，复制结果的成功/失败提示由该 composable 统一处理。`desc` 为空时按钮不渲染。
+
+## desc 解析规则
+
+`data` 是一个 computed，逻辑如下：
+
+```typescript
+const data = computed(() => {
+  try {
+    return JSON.parse(props.desc || ''); // desc 为 undefined/''/null 时 parse('') 会抛出
+  } catch {
+    return props.desc; // 解析失败，原样返回字符串
+  }
+});
+```
+
+模板通过 `typeof data === 'object'` 分支渲染：
+
+| desc 值            | JSON.parse 结果 | typeof 结果 | 渲染方式                 |
+| ------------------ | --------------- | ----------- | ------------------------ |
+| `'{"a":1}'`        | `{ a: 1 }`      | `'object'`  | 键值对列表               |
+| `'[1,2,3]'`        | `[1, 2, 3]`     | `'object'`  | 索引键值对（0:、1:、2:） |
+| `'{}'`             | `{}`            | `'object'`  | 键值对列表（0 行）       |
+| `'"hello"'`        | `"hello"`       | `'string'`  | 纯文本                   |
+| `'42'`             | `42`            | `'number'`  | 纯文本                   |
+| `'普通文本'`       | 解析抛出        | —           | 纯文本（原始字符串）     |
+| `''` / `undefined` | 解析抛出        | —           | 纯文本（空白）           |
+
+> **嵌套对象**：值本身是对象时，文本区域通过 `JSON.stringify(value)` 展示完整 JSON（`HighlightKeyword` + `word-break: break-all`），不再使用悬停 tooltip。
+
+## 基础用法：JSON 参数
+
+```vue
+<template>
+  <DescPanel
+    title="工具调用参数"
+    desc='{"query": "天气查询", "city": "北京", "unit": "celsius"}'
+  />
+</template>
+
+<script setup lang="ts">
+  import { DescPanel } from '@blueking/chat-x';
+</script>
+```
+
+## 纯文本描述
+
+`desc` 不是合法 JSON 时作为纯文本渲染：
+
+```vue
+<template>
+  <DescPanel
+    title="执行说明"
+    desc="正在查询北京的实时天气，请稍候..."
+  />
+</template>
+```
+
+## JSON 数组
+
+JSON 数组同样被视为 `object`，以数组索引（`0:`、`1:`…）作为键渲染：
+
+```vue
+<template>
+  <DescPanel
+    title="文件列表"
+    desc='["report.pdf", "data.csv", "readme.md"]'
+  />
+</template>
+```
+
+## 嵌套 JSON
+
+嵌套对象的值在文本区域直接渲染为 `JSON.stringify(value)` 字符串，便于在面板内换行阅读：
+
+```vue
+<template>
+  <DescPanel
+    title="API 配置"
+    desc='{"endpoint": "/api/search", "headers": {"Authorization": "Bearer xxx", "Content-Type": "application/json"}, "timeout": 5000}'
+  />
+</template>
+```
+
+## 无 desc
+
+`desc` 为可选，不传时面板仅显示标题，内容区域为空，复制按钮也不渲染：
+
+## API
+
+### Props
+
+| 属性名 | 类型     | 必填 | 说明                                                                                |
+| ------ | -------- | ---- | ----------------------------------------------------------------------------------- |
+| title  | `string` | ✓    | 面板标题，始终渲染在顶部（吸顶）                                                    |
+| desc   | `string` | —    | 描述内容；尝试 `JSON.parse`，成功且为 `object` 类型时渲染键值对列表，否则渲染纯文本；有值时才渲染复制按钮 |
+
+## 使用场景
+
+`DescPanel` 主要由 `ToolcallRender` 在展开的详情面板中使用，渲染两块内容：**描述**（`function.description`）与**参数**（`function.arguments`）；工具返回结果则由 `ToolMessage` 再包一层 `DescPanel`（标题「返回内容」）展示。通常不需要手动引入，如需独立使用，直接传入 `title` 和 `desc` 即可。
+
+## 关联组件
+
+- [ToolcallRender](/components/agent/toolcall-render) — 主要使用场景
+- [ToolMessage](/components/message/tool-message) — 工具返回内容面板
+- [HighlightKeyword](/components/helper/highlight-keyword) — 键值高亮
+- [useClipboard](/composables/use-clipboard) — 复制按钮能力来源

package/skills/blueking-chat-x/references/components/detail-section.md

@@ -0,0 +1,91 @@
+# DetailSection 详情分段
+
+> 能力域：Agent 能力 ｜ 导入：`import { DetailSection } from '@blueking/chat-x'` ｜ since 1.0.0
+
+FlowAgent 节点详情中的标题/内容分段容器。 源码位置：src/components/chat-content/flow-agent-content/detail-section.vue。
+
+**关联**：flow-agent-node-detail（节点详情中用于承载基础信息、输入参数、输出参数等区块）、simple-table（常作为分段内容展示结构化参数表格）
+
+---
+
+# DetailSection 详情分段
+
+> **能力域**：Agent 能力
+
+`DetailSection` 是 FlowAgent 节点详情页中的轻量分段容器，用于给一组相关信息提供统一标题样式。组件自身只负责渲染标题和默认插槽，不处理数据格式、折叠、空态或表格逻辑。
+
+通常不需要单独接入，主要由 `FlowAgentNodeDetail` 内部组合使用。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/flow-agent-content/detail-section.vue`
+- **能力说明**：FlowAgent 节点详情中的标题/内容分段容器。
+
+## 核心能力
+
+- **统一标题样式**：标题前带蓝色竖条，标题文本使用详情页统一字号与字重
+- **内容完全透传**：通过默认插槽承载任意内容，如基础信息表单、`SimpleTable` 或自定义说明
+- **无内部状态**：不维护折叠、加载、选择等状态，适合作为详情页布局基础块
+
+## 基础用法
+
+```vue
+<template>
+  <DetailSection title="基础信息">
+    <div class="info-row">节点名称：采集主机指标</div>
+  </DetailSection>
+</template>
+
+<script setup lang="ts">
+  import DetailSection from '@blueking/chat-x/src/components/chat-content/flow-agent-content/detail-section.vue';
+</script>
+```
+
+**渲染效果**
+
+## 搭配 SimpleTable
+
+`DetailSection` 最常见的用法是包裹结构化内容，由外层负责分段标题，内部组件负责数据展示。
+
+```vue
+<template>
+  <DetailSection title="输入参数">
+    <SimpleTable
+      :columns="columns"
+      :data="data"
+    />
+  </DetailSection>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名 | 类型     | 必填 | 默认值 | 说明     |
+| ------ | -------- | ---- | ------ | -------- |
+| title  | `string` | 是   | —      | 分段标题 |
+
+### Emits
+
+- 无。
+
+### Slots
+
+| 插槽名  | 说明             |
+| ------- | ---------------- |
+| default | 分段主体展示内容 |
+
+### Expose
+
+- 无。
+
+## 使用建议
+
+- 用于详情页内部的短分段，不建议作为通用卡片或页面 Section 使用。
+- 内容空态应由插槽内组件自行处理，`DetailSection` 不会主动显示空态。
+
+## 关联组件
+
+- [FlowAgentNodeDetail](./flow-agent-node-detail.md) — 节点详情主体。
+- [SimpleTable](./simple-table.md) — 分段内常用的轻量表格。

package/skills/blueking-chat-x/references/components/execution-summary.md

@@ -0,0 +1,128 @@
+# ExecutionSummary 执行摘要
+
+> 能力域：Agent 能力 ｜ 导入：`import { ExecutionSummary } from '@blueking/chat-x'` ｜ since 1.0.0
+
+按消息流提取执行摘要，支持关键词定位和消息渲染。 源码位置：src/components/execution-summary/execution-summary.vue。
+
+**关联**：message-render（摘要列表内渲染消息内容）、highlight-keyword（搜索关键词注入与高亮）、chat-container（常与侧栏「执行情况」Tab 组合）
+
+---
+
+# ExecutionSummary 执行摘要
+## 源码事实
+
+- **源码位置**：`src/components/execution-summary/execution-summary.vue`
+- **能力域**：Agent 能力
+- **能力说明**：按消息流提取执行摘要，支持关键词定位和消息渲染。
+
+> **能力域**：Agent 能力
+
+执行摘要面板组件，以时间线形式展示对话中的工具调用和 FlowAgent 活动记录。支持关键词搜索过滤和点击定位到对话中的消息位置。
+
+通常不需要直接使用，`ChatContainer` 会在侧边栏的「执行情况」Tab 中自动渲染。
+
+## 核心能力
+
+- **时间线布局**：每组消息按时间节点排列，带连接线
+- **关键词搜索**：实时过滤匹配的执行记录
+- **对话定位**：hover 显示「在对话中定位」按钮，点击滚动到对应消息
+- **空状态处理**：无数据或搜索无结果时显示空状态提示
+
+## 基础用法
+
+```vue
+<template>
+  <ExecutionSummary
+    :message-groups="executionGroups"
+    @locate-message-group="handleLocate"
+    @update-keyword="handleUpdateKeyword"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ExecutionSummary, type MessageGroup } from '@blueking/chat-x';
+
+  const handleLocate = (uid: string, group: MessageGroup) => {
+    const dom = document.getElementById(uid);
+    dom?.scrollIntoView({ behavior: 'smooth' });
+  };
+
+  const handleUpdateKeyword = (keyword: string) => {
+    console.log('搜索关键词:', keyword);
+  };
+</script>
+```
+
+**渲染效果**（包含搜索过滤和定位功能，hover 消息组可看到「在对话中定位」按钮）
+
+## 组件结构
+
+```
+ai-execution-summary
+├── ai-execution-summary-header（仅 messageGroups 非空时渲染）
+│   └── Input（关键词搜索框，clearable）
+└── ai-execution-summary-content
+    ├── 有数据时：
+    │   └── content-item × N（时间线节点）
+    │       ├── timeline-dot（时间节点圆点）
+    │       ├── content-item-time（格式化时间）
+    │       ├── content-item-locate（hover 显示定位按钮）
+    │       ├── content-item-messages（MessageRender × N）
+    │       └── timeline-line（连接线，最后一项不显示）
+    └── 无数据时：
+        └── Exception（scene="part"）+「暂无数据」/「搜索结果为空」文案（有关键词时附带「清空搜索」）
+```
+
+## 空状态
+
+当 `messageGroups` 为空数组时，**不渲染搜索 header**，内容区整块展示空态（bkui `Exception` +「暂无数据」；若仍有搜索关键词则为「搜索结果为空」并提供「清空搜索」）：
+
+## 与 ChatContainer 配合
+
+`ChatContainer` 通过 `useMessageGroup` 计算 `executionGroups`（仅包含工具调用和 FlowAgent 消息），并传给 `ExecutionSummary`：
+
+```vue
+<!-- ChatContainer 内部 -->
+<ExecutionSummary
+  :message-groups="executionGroups"
+  @locate-message-group="handleLocateMessageGroup"
+  @update-keyword="handleUpdateKeyword"
+/>
+```
+
+## API
+
+### Props
+
+| 属性名        | 类型             | 必填 | 说明             |
+| ------------- | ---------------- | ---- | ---------------- |
+| messageGroups | `MessageGroup[]` | ✓    | 执行摘要消息分组 |
+
+### Events
+
+| 事件名             | 参数                                  | 说明                     |
+| ------------------ | ------------------------------------- | ------------------------ |
+| locateMessageGroup | `(uid: string, group: MessageGroup)` | 点击「在对话中定位」按钮，参数为消息组 `MessageGroup.uid` |
+| updateKeyword      | `(keyword: string)`                   | 搜索关键词变更           |
+
+## 类型定义
+
+```typescript
+import { type MessageGroup } from '@blueking/chat-x';
+
+interface MessageGroup {
+  uid: string;
+  type: MessageRole;
+  messages: Message[];
+  checked: boolean;
+  isHover: boolean;
+  pause?: boolean;
+  startTime?: number;
+}
+```
+
+## 关联组件
+
+- [MessageRender](/components/message/message-render) — 摘要内消息渲染
+- [HighlightKeyword](/components/helper/highlight-keyword) — 搜索高亮
+- [ChatContainer](/components/setup/chat-container) — 侧栏挂载场景