@blueking/chat-x 0.0.5 → 0.0.6

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

@@ -0,0 +1,238 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ContentRender 按消息 content 类型分发：字符串走 Markdown 管线，数组可走引用文档等；可扩展自定义 slot。 主要 props 为 content、status，与 MessageRender、AssistantMessage 等配合使用。 内置与 MarkdownContent、ReferenceContent 等原子/分子组件衔接。
+
+### 关联组件
+- **markdown-content** — 文本类 Markdown 正文的默认渲染实现
+- **reference-content** — 引用文档数组类型的列表渲染
+- **assistant-message** — AI 回复中默认通过本组件渲染正文
+
+---
+<!-- FULL DOC -->
+
+# ContentRender 内容渲染器
+
+> **层级**：分子组件 · **功能域**：内容渲染
+
+消息内容渲染分发组件，根据 `content` 的 JavaScript 类型自动选择渲染方式：字符串 → `MarkdownContent`（Markdown 渲染），数组 → `ReferenceContent`（引用列表）。
+
+## 渲染管线
+
+```
+ContentRender
+├── typeof content === 'string'  →  MarkdownContent（Markdown 渲染）
+│   └── status === 'error'       →  CommonErrorContent（红色错误图标 + 文本）
+├── Array.isArray(content)       →  ReferenceContent（引用文档列表）
+└── 其他                         →  undefined（不渲染，可通过 slot 自定义）
+```
+
+> **注意**：渲染类型由 `content` 的 JavaScript 类型决定（字符串 vs 数组），`type` prop 仅当传入 `MessageContentType.Text` 时才强制走 `MarkdownContent`，通常不需要显式传递。
+
+## 基础用法（Markdown 文本）
+
+字符串内容自动渲染为 Markdown：
+
+```vue
+<template>
+  <ContentRender
+    :content="content"
+    :status="status"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ContentRender, MessageStatus } from '@blueking/chat-x';
+
+  const content = '这是一段 **Markdown** 内容，支持 `代码`、**加粗**、*斜体* 等语法。';
+  const status = MessageStatus.Complete;
+</script>
+```
+
+**渲染效果**
+
+## Markdown 语法支持
+
+`MarkdownContent` 内置了完整的 Markdown 解析能力，使用 `markdown-it` + 多个插件：
+
+### 常用语法（代码、列表、表格）
+
+### 扩展语法
+
+| 语法                  | 效果           | 插件                      |
+| --------------------- | -------------- | ------------------------- |
+| `++文字++`            | 下划线（新增） | markdown-it-ins           |
+| `==文字==`            | 高亮标注       | markdown-it-mark          |
+| `^上标^`              | 上标           | markdown-it-sup           |
+| `~下标~`              | 下标           | markdown-it-sub           |
+| `[^1]` / `[^1]: 内容` | 脚注           | markdown-it-footnote      |
+| `- [x] 任务`          | 任务列表       | markdown-it-task-checkbox |
+
+### LaTeX 数学公式
+
+行内公式 `$...$` 和块级公式 `$$...$$`，由 `katex` 渲染：
+
+```vue
+<ContentRender content="行内公式：$E = mc^2$" status="complete" />
+```
+
+### Mermaid 图表
+
+代码块语言标识为 `mermaid` 时，由 `MermaidContent` 专门渲染：
+
+## 消息状态
+
+`status` 只传递给 `MarkdownContent`，对 `ReferenceContent` 无效。
+
+| `status`    | 渲染行为                                                          |
+| ----------- | ----------------------------------------------------------------- |
+| `complete`  | 正常渲染完整 Markdown                                             |
+| `streaming` | 自动补全未闭合的 Markdown 语法（代码块、列表等），节流解析（5ms） |
+| `pending`   | 同 `complete`（按当前内容渲染）                                   |
+| `error`     | 渲染为 `CommonErrorContent`（红色错误图标 + `content` 文本）      |
+| `stop`      | 同 `complete`                                                     |
+
+**错误状态示例**
+
+## 引用文档列表
+
+`content` 传入 `ReferenceDocumentContent[]` 数组时，自动渲染为 `ReferenceContent`（引用文档列表）：
+
+```vue
+<template>
+  <ContentRender :content="referenceContent" />
+</template>
+
+<script setup lang="ts">
+  import { ContentRender, type ReferenceDocumentContent } from '@blueking/chat-x';
+
+  const referenceContent: ReferenceDocumentContent[] = [
+    {
+      name: 'Vue 3 官方文档',
+      url: 'https://vuejs.org',
+      originFile: 'vue3-guide.md', // 有 originFile 时显示预览和跳转图标
+    },
+    {
+      name: 'TypeScript 手册',
+      url: 'https://www.typescriptlang.org',
+      originFile: '', // 无 originFile 时不显示操作图标
+    },
+  ];
+</script>
+```
+
+**渲染效果**（悬停条目查看图标，有 `originFile` 的条目显示预览和跳转图标）
+
+### ReferenceContent 图标显示规则
+
+| 条件                           | 显示图标                                     |
+| ------------------------------ | -------------------------------------------- |
+| 始终                           | 文档图标（红色）                             |
+| `url` 和 `originFile` 均不为空 | 预览图标（悬停可见）                         |
+| `url` 和 `originFile` 均不为空 | 跳转图标（悬停可见，打开 `originFile` 链接） |
+
+无 `originFile` 时只显示文档图标（点击文档名跳转 `url`）：
+
+## 自定义渲染（默认插槽）
+
+默认插槽接收 `{ content }` 参数（原始 `content` prop 值），替换整个内容渲染：
+
+```vue
+<template>
+  <ContentRender
+    :content="content"
+    :status="status"
+  >
+    <template #default="{ content }">
+      <div class="custom-content">
+        <h3>自定义渲染</h3>
+        <pre>{{ JSON.stringify(content, null, 2) }}</pre>
+      </div>
+    </template>
+  </ContentRender>
+</template>
+
+<script setup lang="ts">
+  import { ContentRender } from '@blueking/chat-x';
+
+  const content = '自定义内容，由 slot 接管渲染。';
+  const status = 'complete';
+</script>
+```
+
+**渲染效果**
+
+## API
+
+### Props
+
+| 属性名  | 类型                                   | 必填 | 说明                                                                                      |
+| ------- | -------------------------------------- | ---- | ----------------------------------------------------------------------------------------- |
+| content | `string \| ReferenceDocumentContent[]` | ✅   | 内容数据，字符串走 Markdown 渲染，数组走引用文档列表渲染                                  |
+| status  | `MessageStatus`                        | -    | 消息状态，只影响 Markdown 渲染（`error` 时渲染错误样式，`streaming` 时补全语法）          |
+| type    | `ContentType`                          | -    | 内容类型提示，传入 `MessageContentType.Text` 可强制走 MarkdownContent；通常不需要显式传递 |
+
+### Slots
+
+| 插槽名  | 参数                         | 说明                                                   |
+| ------- | ---------------------------- | ------------------------------------------------------ |
+| default | `{ content: ContentMap[T] }` | 自定义渲染，接收原始 content prop 值，替换全部默认逻辑 |
+
+## 流式渲染机制
+
+`streaming` 状态下，`MarkdownContent` 有以下优化：
+
+1. **语法自动补全**：`completeMarkdownSyntax` 在解析前补全未闭合的代码块、列表等，避免渲染异常
+2. **节流解析**：`parseMarkdownContent` 节流 5ms（leading + trailing），大幅降低流式输入时的解析开销
+3. **不完整状态保护**：当正在输入 LaTeX 命令（如 `$\fra...`）时保持之前的渲染结果，避免闪烁
+4. **CSS contain 性能隔离**：`.markdown-content` 使用 `contain: layout style`，`.markdown-body` 使用 `contain: content`，减少重排影响范围
+5. **自动滚动**：每个 token 挂载后触发 `toScrollBottom()`（节流 100ms），与 `MessageContainer` 配合实现流式自动滚动
+
+## 类型定义
+
+```typescript
+import { MessageContentType, MessageStatus } from '@blueking/chat-x';
+
+// 引用文档内容
+type ReferenceDocumentContent = {
+  name: string; // 显示名称（为空时该条目被过滤，不渲染）
+  url: string; // 文档访问地址（点击文档名跳转）
+  originFile: string; // 原始文件地址（非空时显示预览和跳转图标）
+};
+
+// 内容类型（ContentType = keyof ContentMap）
+enum MessageContentType {
+  Text = 'text', // 字符串，Markdown 渲染
+  ReferenceDocument = 'reference_document', // ReferenceDocumentContent[]，引用列表
+  Binary = 'binary',
+  Function = 'function',
+  KeyValue = 'key-value',
+  KnowledgeRag = 'knowledge_rag',
+  Other = 'other',
+}
+
+// 消息状态
+enum MessageStatus {
+  Pending = 'pending',
+  Streaming = 'streaming',
+  Complete = 'complete',
+  Error = 'error',
+  Stop = 'stop',
+  Disabled = 'disabled',
+}
+```
+
+## 使用场景
+
+- **AI 文本回复渲染**：`AssistantMessage` 内部用 `ContentRender` 渲染 AI 回复内容，`status` 配合流式响应
+- **知识库引用展示**：`ActivityMessage` 内部用 `ContentRender` 渲染引用文档列表
+- **代码展示**：Markdown 代码块由 `CodeContent` 自动高亮（Atom One Dark 主题，支持 180+ 语言）
+- **数学公式**：行内 `$...$` 和块级 `$$...$$`，由 KaTeX 渲染
+- **流程图**：Mermaid 代码块自动渲染为 SVG 图表
+- **自定义渲染**：通过 slot 接管渲染，实现表格、图表等自定义内容展示
+
+## 关联组件
+
+- [MarkdownContent](../atomic/markdown-content.md) — 字符串 Markdown 正文
+- [ReferenceContent](../atomic/reference-content.md) — 引用文档数组
+- [AssistantMessage](./assistant-message.md) — assistant 消息中默认使用

package/dist/mcp/generated/docs/delete-tool.md

@@ -0,0 +1,188 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+DeleteTool 在点击删除图标后弹出 Tippy 确认层，需再次点击「删除」才 emit confirm，避免误删。 触发器为 ToolBtn；MessageTools 在工具 id 为 delete 时用本组件替换普通 ToolBtn。
+
+### 关联组件
+- **tool-btn** — 删除图标与触发入口
+- **message-tools** — delete 工具 id 时自动采用本组件
+
+---
+<!-- FULL DOC -->
+
+# DeleteTool 删除确认按钮
+
+> **层级**：分子组件 · **功能域**：工具与反馈
+
+删除操作的二次确认组件。点击删除图标后弹出确认弹窗，用户需再次点击"删除"按钮才会触发 `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](../atomic/tool-btn.md) — 触发按钮
+- [MessageTools](./message-tools.md) — 工具栏中 delete 替换入口

package/dist/mcp/generated/docs/desc-panel.md

@@ -0,0 +1,139 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+DescPanel 将描述字符串尝试 JSON 解析为键值列表展示，否则按纯文本输出，用于工具调用详情折叠区。 内部对键与值使用 HighlightKeyword 支持搜索高亮。
+
+### 关联组件
+- **toolcall-render** — 工具调用详情中渲染描述与参数
+- **highlight-keyword** — 键值与文本匹配关键词高亮
+
+---
+<!-- FULL DOC -->
+
+# DescPanel 描述面板
+
+> **层级**：原子组件 · **功能域**：辅助组件
+
+工具调用（ToolCall）详情面板的描述区域组件，主要用于 `ToolcallRender` 内部的折叠面板中。
+
+将 `desc` 字符串尝试解析为 JSON，解析成功且结果为对象/数组时以键值对列表渲染，否则作为纯文本展示。
+
+## 组件结构
+
+```
+.toolcall-desc（flex column，gap: 4px，padding: 12px，background: #f5f7fa）
+├── .desc-title（font-size: 12px，font-weight: bold，color: #313238，margin-bottom: 6px）
+│     └── {{ title }}
+└── .desc-panel（flex column，gap: 4px）
+      ├── [JSON 对象/数组] v-for 逐项渲染 .desc-panel-item
+      │     ├── .desc-label  → "{{ key }}:"
+      │     └── .desc-value（overflow hidden，ellipsis，nowrap）
+      │           └── v-overflow-tips → hover 时显示完整内容
+      │               · value 为对象/数组时，tooltip 显示 JSON.stringify(value)
+      │               · value 为原始值时，tooltip 显示原始值
+      └── [非 JSON / 解析失败] 直接渲染 {{ data }}（纯文本）
+```
+
+## 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` | 解析抛出        | —           | 纯文本（空白）           |
+
+> **嵌套对象**：值本身是对象时，`{{ value }}` 渲染为 `[object Object]`，但 `v-overflow-tips` 的 tooltip 会显示 `JSON.stringify(value)` 的完整内容，方便查看原始结构。
+
+## 基础用法：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
+
+嵌套对象的值通过 `v-overflow-tips` 悬停后显示 JSON.stringify 结果，文本区域显示 `[object Object]`：
+
+```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` 内部在折叠面板中使用，分别用于渲染工具调用的 **输入参数**（`arguments`）和 **输出结果**（`toolMessage.description`）。通常不需要手动引入，如需独立使用，直接传入 `title` 和 `desc` 即可。
+
+## 关联组件
+
+- [ToolcallRender](../molecular/toolcall-render.md) — 主要使用场景
+- [HighlightKeyword](./highlight-keyword.md) — 键值高亮

package/dist/mcp/generated/docs/execution-summary.md

@@ -0,0 +1,126 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ExecutionSummary 以时间线汇总工具调用与 FlowAgent 等活动记录，支持关键词过滤与 HighlightKeyword 高亮。 点击可 emit 定位到会话中对应消息；内部用 MessageRender 渲染摘要条目中的消息片段。
+
+### 关联组件
+- **message-render** — 摘要列表内渲染消息内容
+- **highlight-keyword** — 搜索关键词注入与高亮
+- **chat-container** — 常与侧栏「执行情况」Tab 组合
+
+---
+<!-- FULL DOC -->
+
+# ExecutionSummary 执行摘要
+
+> **层级**：分子组件 · **功能域**：辅助组件
+
+执行摘要面板组件，以时间线形式展示对话中的工具调用和 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 = (uuid: string, group: MessageGroup) => {
+    const dom = document.getElementById(uuid);
+    dom?.scrollIntoView({ behavior: 'smooth' });
+  };
+
+  const handleUpdateKeyword = (keyword: string) => {
+    console.log('搜索关键词:', keyword);
+  };
+</script>
+```
+
+**渲染效果**（包含搜索过滤和定位功能，hover 消息组可看到「在对话中定位」按钮）
+
+## 组件结构
+
+```
+execution-summary
+├── execution-summary-header
+│   └── Input（关键词搜索框，clearable）
+└── execution-summary-content
+    ├── 有数据时：
+    │   └── content-item × N（时间线节点）
+    │       ├── timeline-dot（时间节点圆点）
+    │       ├── content-item-time（格式化时间）
+    │       ├── content-item-locate（hover 显示定位按钮）
+    │       ├── content-item-messages（MessageRender × N）
+    │       └── timeline-line（连接线，最后一项不显示）
+    └── 无数据时：
+        └── Exception（空状态）+ 清空搜索按钮
+```
+
+## 空状态
+
+当 `messageGroups` 为空数组时，显示空状态提示：
+
+## 与 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 | `(uuid: string, group: MessageGroup)` | 点击「在对话中定位」按钮 |
+| updateKeyword      | `(keyword: string)`                   | 搜索关键词变更           |
+
+## 类型定义
+
+```typescript
+import { type MessageGroup } from '@blueking/chat-x';
+
+interface MessageGroup {
+  uuid: string;
+  type: MessageRole;
+  messages: Message[];
+  checked: boolean;
+  isHover: boolean;
+  pause?: boolean;
+  startTime?: number;
+}
+```
+
+## 关联组件
+
+- [MessageRender](./message-render.md) — 摘要内消息渲染
+- [HighlightKeyword](../atomic/highlight-keyword.md) — 搜索高亮
+- [ChatContainer](./chat-container.md) — 侧栏挂载场景