@blueking/chat-x 0.0.4 → 0.0.6

package/dist/mcp/generated/docs/use-custom-tab.md

@@ -0,0 +1,122 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。
+
+### 关联组件
+- **chat-container** — Provider 与侧栏 Tab 主场景
+
+---
+<!-- FULL DOC -->
+
+# useCustomTab 自定义 Tab 管理
+
+> **分类**：composable
+
+Provider/Consumer 模式的自定义 Tab 管理，用于 `ChatContainer` 侧边栏的 Tab 动态管理。Provider 在 `ChatContainer` 中创建，Consumer 在任意后代组件中注入使用。
+
+## 函数签名
+
+### useCustomTabProvider
+
+```typescript
+function useCustomTabProvider<T extends Record<string, unknown>>(options: {
+  onTabChange?: (tab: CustomTab<T>) => void;
+}): {
+  tabs: ShallowRef<CustomTab<T>[]>;
+  selectedTab: Ref<CustomTab<T>>;
+  isCollapse: ShallowRef<boolean>;
+  addCustomTab: (tab: CustomTab<T>) => void;
+  removeCustomTab: (tabName: string) => void;
+  selectCustomTab: (tab: CustomTab<T>) => void;
+};
+```
+
+### useCustomTabConsumer
+
+```typescript
+function useCustomTabConsumer<T extends Record<string, unknown>>():
+  | undefined
+  | {
+      tabs: ShallowRef<CustomTab<T>[]>;
+      selectedTab: ShallowRef<CustomTab<T> | null>;
+      addCustomTab: (tab: CustomTab<T>) => void;
+      removeCustomTab: (tabName: string) => void;
+      selectCustomTab: (tab: CustomTab<T>) => void;
+    };
+```
+
+## 使用示例
+
+### Provider（容器组件）
+
+```typescript
+import { useCustomTabProvider, EXECUTION_TAB_NAME } from '@blueking/chat-x';
+
+const { tabs, selectedTab, isCollapse, addCustomTab, removeCustomTab, selectCustomTab } = useCustomTabProvider({
+  onTabChange: async tab => {
+    // Tab 切换时加载数据
+    const data = await fetchTabData(tab.name);
+    return data;
+  },
+});
+```
+
+### Consumer（后代组件）
+
+```typescript
+import { useCustomTabConsumer } from '@blueking/chat-x';
+
+const tabManager = useCustomTabConsumer();
+
+// 添加一个自定义 Tab
+tabManager?.addCustomTab({
+  name: 'node-detail-123',
+  label: '节点详情',
+  data: {
+    component: NodeDetailComponent,
+    props: { nodeId: '123' },
+  },
+});
+
+// 移除 Tab
+tabManager?.removeCustomTab('node-detail-123');
+```
+
+## 内置常量
+
+| 常量名               | 值            | 说明                      |
+| -------------------- | ------------- | ------------------------- |
+| `EXECUTION_TAB_NAME` | `'execution'` | 执行情况 Tab 的固定标识   |
+| `CUSTOM_TAB_TOKEN`   | `Symbol`      | provide/inject 注入 Token |
+
+## 返回值说明
+
+| 属性/方法名     | 类型                        | 说明                                              |
+| --------------- | --------------------------- | ------------------------------------------------- |
+| tabs            | `ShallowRef<CustomTab[]>`   | 所有 Tab 列表（含默认的执行情况 Tab）             |
+| selectedTab     | `Ref<CustomTab>`            | 当前选中的 Tab                                    |
+| isCollapse      | `ShallowRef<boolean>`       | 侧边栏折叠状态；`addCustomTab` 时自动设为 `false` |
+| addCustomTab    | `(tab: CustomTab) => void`  | 添加 Tab（同名 Tab 不重复添加）                   |
+| removeCustomTab | `(tabName: string) => void` | 移除指定 Tab                                      |
+| selectCustomTab | `(tab: CustomTab) => void`  | 切换到指定 Tab，触发 `onTabChange` 回调           |
+
+## 类型定义
+
+```typescript
+interface CustomTab<T = Record<string, unknown>> {
+  label: string;
+  name: string;
+  data?: T;
+}
+```
+
+## 设计特点
+
+- `tabs` 使用 `shallowRef`，`addCustomTab` 通过展开新数组触发更新，避免 `UnwrapRef<T>` 类型问题
+- 默认的「执行情况」Tab 始终存在且不可关闭
+- `addCustomTab` 同时展开侧边栏（`isCollapse = false`）并在 `nextTick` 后自动选中新 Tab
+
+## 关联组件
+
+- [ChatContainer](../components/molecular/chat-container.md) — 侧栏 Tab 与自定义面板

package/dist/mcp/generated/docs/use-global-config.md

@@ -0,0 +1,154 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useGlobalConfig 提供 messageSlotId（'#ai-blueking-message-slot'）与 rawMessageSlotId，并 provide AI_BLUEKING_MESSAGE_SLOT_ID。 useMessageSlotId 在子组件 inject 得到 ShallowRef，供 Teleport :to 挂载到消息容器内节点。名称易误解为全局配置，仅与 Teleport 插槽相关。 ChatContainer 使用 useMessageSlotId 与 messageSlotId；FlowMessage 等用 Teleport 展示详情。
+
+### 关联组件
+- **chat-container** — 侧栏 messageSlotId 与自定义 Tab 内容区
+- **flow-message** — useMessageSlotId + Teleport 流程详情
+
+---
+<!-- FULL DOC -->
+
+# useGlobalConfig 消息面板 Teleport 插槽
+
+> **分类**：composable
+
+为消息容器内的子组件提供共享 **Teleport 目标 ID** 的 Provider/Consumer 工具。
+
+根容器注册一个 `id="ai-blueking-message-slot"` 的 DOM 节点，并通过 `provide` 将其 CSS 选择器下发；子组件（如 `FlowMessage`）通过 `inject` 取到该选择器，作为 `<Teleport :to="...">` 的挂载目标，从而将详情面板等覆盖层 Teleport 到消息容器内部的指定位置，而非 `body`。
+
+> 名称"useGlobalConfig"具有一定误导性——该模块实际上**只负责管理 Teleport 插槽 ID**，不涉及任何 locale / zIndex 等通用全局配置。
+
+## 工作原理
+
+```
+根容器组件
+  ├── useGlobalConfig()
+  │     ├── provide(AI_BLUEKING_MESSAGE_SLOT_ID, computed(() => '#ai-blueking-message-slot'))
+  │     └── return { messageSlotId: '#ai-blueking-message-slot', rawMessageSlotId: 'ai-blueking-message-slot' }
+  │
+  └── <div :id="rawMessageSlotId" />  ← Teleport 实际挂载的 DOM 节点
+
+后代子组件（如 FlowMessage）
+  ├── useMessageSlotId()
+  │     ├── onMounted → watchEffect → inject(AI_BLUEKING_MESSAGE_SLOT_ID).value
+  │     └── return { messageSlotId: ShallowRef<'#ai-blueking-message-slot' | undefined> }
+  │
+  └── <Teleport :to="messageSlotId">   ← Teleport 至根容器内
+        <FlowDetail />
+      </Teleport>
+```
+
+## 渲染示例
+
+## 根容器用法（useGlobalConfig）
+
+```vue
+<template>
+  <div class="chat-container">
+    <!-- 1. 创建 Teleport 挂载目标 DOM 节点 -->
+    <div
+      :id="rawMessageSlotId"
+      class="ai-blueking-container-slot"
+    />
+
+    <!-- 2. 消息列表（FlowMessage 等子组件从此处注入插槽 ID） -->
+    <MessageRender :messages="messages" />
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { useGlobalConfig } from '@blueking/chat-x';
+
+  // provide 插槽 ID 给所有后代，同时获取 rawMessageSlotId 作为 DOM id
+  const { rawMessageSlotId } = useGlobalConfig();
+</script>
+```
+
+## 子组件用法（useMessageSlotId）
+
+```vue
+<!-- FlowMessage 内部（简化） -->
+<template>
+  <div class="flow-message">
+    <!-- 节点列表... -->
+
+    <!-- 点击节点后，将详情面板 Teleport 到根容器的插槽节点 -->
+    <template v-if="detailVisible && messageSlotId">
+      <Teleport :to="messageSlotId">
+        <FlowDetail
+          :node="selectedNode"
+          @close="detailVisible = false"
+        />
+      </Teleport>
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { useMessageSlotId } from '@blueking/chat-x';
+
+  // 注入根容器提供的 CSS 选择器（'#ai-blueking-message-slot'）
+  const { messageSlotId } = useMessageSlotId();
+</script>
+```
+
+## API
+
+### useGlobalConfig()
+
+```typescript
+function useGlobalConfig(): {
+  messageSlotId: ComputedRef<string>; // '#ai-blueking-message-slot'（CSS 选择器）
+  readonly rawMessageSlotId: string; // 'ai-blueking-message-slot'（DOM id 属性值）
+};
+```
+
+- 调用后立即 `provide(AI_BLUEKING_MESSAGE_SLOT_ID, messageSlotId)` 向后代注入
+- 必须在 Vue 组件的 `setup()` 中调用（有组件上下文才能 `provide`）
+
+### useMessageSlotId()
+
+```typescript
+function useMessageSlotId(): {
+  messageSlotId: ShallowRef<string | undefined>;
+  // 初始值：undefined（onMounted 前）
+  // 挂载后：'#ai-blueking-message-slot'（由 inject 注入）
+};
+```
+
+- `onMounted` 后通过 `watchEffect` + `inject` 填充 `messageSlotId.value`
+- 无父级 Provider 时 `inject` 返回 `undefined`，`messageSlotId.value` 保持 `undefined`
+- 使用前建议配合 `v-if="messageSlotId"` 防止 Teleport 找不到目标
+
+### getMessageSlotId()（内部辅助）
+
+```typescript
+function getMessageSlotId(): ComputedRef<string> | undefined;
+// = inject(AI_BLUEKING_MESSAGE_SLOT_ID)
+```
+
+- 由 `useMessageSlotId` 内部调用，通常不需要直接使用
+
+### 导出常量
+
+```typescript
+// Teleport 目标元素的 id 属性值
+export const MESSAGE_SLOT_ID = 'ai-blueking-message-slot';
+
+// provide/inject 使用的 Symbol key
+export const AI_BLUEKING_MESSAGE_SLOT_ID: unique symbol;
+```
+
+## 注意事项
+
+1. **`useGlobalConfig` 必须在祖先组件调用**：子组件的 `useMessageSlotId` 通过 `inject` 获取，必须在同一组件树内存在对应 Provider
+2. **`messageSlotId` 在 `onMounted` 后才有值**：`useMessageSlotId` 的返回值初始为 `undefined`，应配合 `v-if="messageSlotId"` 防止 Teleport 报错
+3. **DOM 节点必须与 `rawMessageSlotId` 对应**：根容器需确保 `<div :id="rawMessageSlotId">` 存在于 DOM 中，Teleport 才能找到目标
+4. **Teleport 目标在消息容器内**：相比直接 Teleport 到 `body`，此方案让覆盖层随消息容器的布局、z-index、overflow 上下文保持一致
+
+## 关联组件
+
+- [ChatContainer](../components/molecular/chat-container.md) — 侧栏插槽节点与 messageSlotId
+- [FlowMessage](../components/molecular/flow-message.md) — Teleport 流程节点详情

package/dist/mcp/generated/docs/use-menu-keydown.md

@@ -0,0 +1,164 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useMenuKeydown 接收 items、menuRef、onSelect，在 window 捕获阶段监听 keydown；菜单不可见（offsetParent 为空）或列表为空时不响应。 维护 activeIndex，处理 ArrowUp/ArrowDown 循环与 Enter 选中，并 scrollIntoView 当前 .is-active 项。 AiSlashMenu、AiPromptList（ChatInput 子模块）内部使用。
+
+### 关联组件
+- **chat-input** — AiSlashMenu / AiPromptList 键盘导航
+
+---
+<!-- FULL DOC -->
+
+# useMenuKeydown 菜单键盘导航
+
+> **分类**：composable
+
+为弹出菜单提供键盘导航能力的组合式函数。在 `onMounted` 时于 **`window` 捕获阶段**注册 `keydown` 监听，在 `onScopeDispose` 时自动移除，通过 `menuRef.offsetParent` 检测菜单可见性来决定是否响应按键。
+
+内部维护 `activeIndex`（高亮项索引），由调用方将其绑定到列表的 `.is-active` 样式；`handleKeydown` 完全内部管理，**无需手动绑定到模板**。
+
+## 工作原理
+
+```
+onMounted：window.addEventListener('keydown', handleKeydown, true)  ← 捕获阶段
+onScopeDispose：window.removeEventListener('keydown', handleKeydown, true)
+
+handleKeydown(e):
+  ├── !menuRef.value?.offsetParent → return（菜单不可见，忽略）
+  ├── !items.value?.length        → return（列表为空，忽略）
+  │
+  ├── ArrowUp   → e.preventDefault/stopPropagation
+  │               activeIndex = (activeIndex - 1 + length) % length  ← 循环到末尾
+  │               scrollToActive()
+  ├── ArrowDown → e.preventDefault/stopPropagation
+  │               activeIndex = (activeIndex + 1) % length           ← 循环到开头
+  │               scrollToActive()
+  └── Enter / NumpadEnter → e.preventDefault/stopPropagation
+                            onSelect(items[activeIndex])
+
+scrollToActive()：nextTick → menuRef.querySelector('.is-active')?.scrollIntoView({ block: 'nearest' })
+```
+
+> **`.is-active` 依赖**：`scrollToActive` 通过 CSS 类名 `.is-active` 定位当前高亮项，调用方必须在模板中将 `activeIndex` 对应的项加上此类名。
+
+## 渲染示例
+
+使用 ↑ ↓ 键移动高亮，Enter 选中：
+
+## 基础用法
+
+```vue
+<template>
+  <!-- 菜单容器，ref 传给 useMenuKeydown 用于可见性检测 -->
+  <div
+    ref="menuRef"
+    class="prompt-menu"
+  >
+    <div
+      v-for="(item, i) in items"
+      :key="item.id"
+      :class="['menu-item', { 'is-active': activeIndex === i }]"
+      @click="onSelect(item)"
+      @mouseenter="activeIndex = i"
+    >
+      {{ item.name }}
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { shallowRef, useTemplateRef } from 'vue';
+  import { useMenuKeydown } from '@blueking/chat-x';
+
+  const menuRef = useTemplateRef<HTMLElement>('menuRef');
+  const items = shallowRef([
+    { id: 'ask', name: '问问小鲸' },
+    { id: 'translate', name: '翻译文本' },
+    { id: 'review', name: '代码审查' },
+  ]);
+
+  const onSelect = (item: (typeof items.value)[0]) => {
+    console.log('选中：', item.name);
+  };
+
+  // activeIndex 由 composable 内部管理，无需手动传入
+  // window keydown 监听自动注册，无需手动绑定 @keydown
+  const { activeIndex } = useMenuKeydown({ items, menuRef, onSelect });
+</script>
+
+<style scoped>
+  .menu-item.is-active {
+    background: #e1ecff;
+    color: #3a84ff;
+  }
+</style>
+```
+
+## 在 AiSlashInput 内部的实际用法
+
+`useMenuKeydown` 被 `AiSlashMenu`（`@` 资源菜单）和 `AiPromptList`（`/` 提示词列表）内部使用：
+
+```typescript
+// AiPromptList 中
+const promptListRef = useTemplateRef<HTMLElement>('promptListRef');
+const { activeIndex } = useMenuKeydown<string>({
+  items: computed(() => props.prompts), // ComputedRef 也可传入
+  onSelect: props.onSelect,
+  menuRef: promptListRef,
+});
+
+// AiSlashMenu 中
+const menuRef = useTemplateRef<HTMLElement>('menuRef');
+const { activeIndex } = useMenuKeydown<IAiSlashMenuItem>({
+  items: sortedResourceList,
+  onSelect: props.onSelect,
+  menuRef,
+});
+```
+
+## API
+
+### 参数
+
+```typescript
+useMenuKeydown<T>(props: {
+  items: ShallowRef<T[]>;                          // 菜单项列表
+  menuRef: Readonly<ShallowRef<HTMLElement | null>>; // 菜单容器 DOM 引用（用于可见性检测和滚动定位）
+  onSelect: (item: T) => void;                     // 选中回调
+}): { activeIndex: ShallowRef<number> }
+```
+
+### 参数说明
+
+| 参数       | 类型                              | 说明                                                        |
+| ---------- | --------------------------------- | ----------------------------------------------------------- |
+| `items`    | `ShallowRef<T[]>`                 | 菜单项数组；为空时所有按键均不响应                          |
+| `menuRef`  | `ShallowRef<HTMLElement \| null>` | 菜单容器引用；`offsetParent === null`（不可见）时按键不响应 |
+| `onSelect` | `(item: T) => void`               | Enter 确认时触发，传入当前 `activeIndex` 对应的项           |
+
+### 返回值
+
+| 属性名        | 类型                 | 初始值 | 说明                                                                           |
+| ------------- | -------------------- | ------ | ------------------------------------------------------------------------------ |
+| `activeIndex` | `ShallowRef<number>` | `0`    | 当前高亮项索引；需在模板中绑定 `.is-active` 类；鼠标 `mouseenter` 也可修改此值 |
+
+### 按键行为（硬编码，不可自定义）
+
+| 按键                    | 行为                                   |
+| ----------------------- | -------------------------------------- |
+| `ArrowUp`               | 高亮上一项（从第 0 项循环到末尾）      |
+| `ArrowDown`             | 高亮下一项（从末尾循环到第 0 项）      |
+| `Enter` / `NumpadEnter` | 选中当前高亮项，调用 `onSelect`        |
+| `Escape`                | 无处理（不在此 composable 负责范围内） |
+
+## 注意事项
+
+1. **`handleKeydown` 内部自动注册**：在 `window` 捕获阶段（第三参数 `true`）绑定，优先于页面其他元素；调用方**无需**手动绑定 `@keydown`
+2. **`.is-active` 类名约定**：`scrollToActive` 通过 `menuRef.querySelector('.is-active')` 定位元素，项目模板必须在 `activeIndex === i` 时添加此类
+3. **`activeIndex` 不自动重置**：列表内容（`items`）变化时，`activeIndex` 保持不变。如需重置（如过滤后），需在外部 `watch` items 并手动将 `activeIndex.value = 0`
+4. **可见性检测依赖 `offsetParent`**：元素通过 `display:none` 隐藏时 `offsetParent === null`，按键会被忽略；`visibility:hidden` 或 `opacity:0` 不会被忽略
+5. **捕获阶段拦截**：`ArrowUp`/`ArrowDown`/`Enter` 均调用 `e.preventDefault()` 和 `e.stopPropagation()`，防止方向键滚动页面或 Enter 提交表单
+
+## 关联组件
+
+- [ChatInput](../components/molecular/chat-input.md) — `@` 菜单与 `/` 提示词列表

package/dist/mcp/generated/docs/use-message-group.md

@@ -0,0 +1,175 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useMessageGroup 接收 keyword、messages、selectedUserMessages，通过 watchEffect 产出 messageGroups（User/Assistant/Tool 合并、末尾 Loading 注入、pause 与分享勾选等）。 executionGroups 供侧边执行摘要过滤，并暴露 isShareMode、全选与 onConfirmShare。 ChatContainer 组装后传给 MessageContainer；ExecutionSummary 消费 executionGroups。
+
+### 关联组件
+- **chat-container** — 调用并传入 MessageContainer
+- **message-container** — 必填 messageGroups 数据源
+- **execution-summary** — 使用 executionGroups 与定位
+
+---
+<!-- FULL DOC -->
+
+# useMessageGroup 消息分组
+
+> **分类**：composable
+
+核心消息分组逻辑，将原始 `Message[]` 数组转换为结构化的 `MessageGroup[]`。处理 Tool 消息合并、Loading 自动注入、执行摘要过滤和消息多选/分享等逻辑。
+
+## 函数签名
+
+```typescript
+function useMessageGroup(options: {
+  keyword?: ShallowRef<string>;
+  messages: ComputedRef<Message[]>;
+  selectedUserMessages: Ref<Message[] | undefined>;
+}): {
+  messageGroups: Ref<MessageGroup[]>;
+  executionGroups: ComputedRef<MessageGroup[]>;
+  isShareMode: ShallowRef<boolean>;
+  isAllSelected: ComputedRef<boolean>;
+  onToggleShareAll: (isAllSelected: boolean) => void;
+  onCancelShare: () => void;
+  onConfirmShare: () => Message[];
+};
+```
+
+## 分组规则
+
+`watchEffect` 遍历 `messages` 数组，按以下规则分组：
+
+```
+messages 原始数组（按顺序处理）
+         │
+    ┌────┴────┐────────────┐
+    │         │            │
+role=user  role=tool     其他 role
+    │         │            │
+ ① 将累积的    ② 通过          ③ 累积到
+ assistant     toolCallId     assistantMessages
+ 消息推入       找到对应的      等待 user 消息
+ list 作为      Assistant       触发分组
+ 一组，当前     消息，注入
+ user 单独      toolMessage
+ 成组           后 continue
+
+④ 遍历结束后将剩余 assistantMessages 推入 list
+⑤ 末尾为 user 消息 → 追加 Loading 消息组
+```
+
+### Tool 消息处理
+
+`role: 'tool'` 消息不会独立渲染，而是通过 `toolCallId` 注入到对应 AssistantMessage 的 `toolCall.toolMessage` 字段：
+
+```typescript
+// 查找对应的 Assistant 消息
+const toolMessage = messages.find(m => m.role === 'assistant' && m.toolCalls?.some(t => t.id === message.toolCallId));
+// 注入到 toolCall
+const toolCall = toolMessage.toolCalls.find(t => t.id === message.toolCallId);
+toolCall.toolMessage = message;
+```
+
+### pause 字段
+
+每个 Assistant 消息组计算 `pause` 属性：
+
+```typescript
+pause = assistantMessages.some(m => m.property?.extra?.pause) ?? false;
+```
+
+`pause` 为 `true` 时，`MessageContainer` 不渲染该组的 `MessageTools` 工具栏。
+
+## executionGroups
+
+`executionGroups` 从 `messageGroups` 中过滤出执行类消息，供 `ExecutionSummary` 使用。每个执行组会自动从前一组用户消息中提取 `userMessageTitle`，作为执行摘要的标题显示；若无前置用户消息则回退为当前时间戳：
+
+```typescript
+const isExecutionMessage = (m: Message): boolean => {
+  return (
+    // 带 toolCalls 的 assistant 消息
+    (m.role === 'assistant' && !!m.toolCalls?.length) ||
+    // FlowAgent 类型的 activity 消息
+    (m.role === 'activity' && m.activityType === 'flow_agent')
+  );
+};
+```
+
+支持关键词过滤，通过 `SEARCH_TEXT_EXTRACTORS` 注册表扩展可搜索文本：
+
+| 消息类型   | 搜索范围                                                     |
+| ---------- | ------------------------------------------------------------ |
+| toolCall   | `function.name`、`mcpName`、`description`、`arguments`、`id` |
+| flow_agent | `task_name`、各节点 `name`                                   |
+
+## 分享模式
+
+`useMessageGroup` 提供完整的分享模式支持：
+
+```typescript
+const {
+  isShareMode, // 是否处于分享模式
+  isAllSelected, // 是否全选
+  onToggleShareAll, // 切换全选
+  onCancelShare, // 取消分享（清空选中 + 退出分享模式）
+  onConfirmShare, // 确认分享（返回选中的消息）
+} = useMessageGroup(options);
+```
+
+选中联动规则：
+
+- 选中用户消息组 → 其后紧邻的 AI 回复组视觉联动选中
+- 取消用户消息组 → 关联 AI 回复组同时取消
+
+## 使用示例
+
+```typescript
+import { computed, ref as deepRef, shallowRef } from 'vue';
+import { useMessageGroup, type Message } from '@blueking/chat-x';
+
+const keyword = shallowRef('');
+const messages = computed(() => props.messages);
+const selectedUserMessages = deepRef<Message[]>([]);
+
+const { messageGroups, executionGroups, isShareMode, isAllSelected, onToggleShareAll, onCancelShare, onConfirmShare } =
+  useMessageGroup({
+    keyword,
+    messages,
+    selectedUserMessages,
+  });
+```
+
+## 返回值说明
+
+| 属性/方法名      | 类型                          | 说明                                                                        |
+| ---------------- | ----------------------------- | --------------------------------------------------------------------------- |
+| messageGroups    | `Ref<MessageGroup[]>`         | 完整消息分组列表                                                            |
+| executionGroups  | `ComputedRef<MessageGroup[]>` | 仅包含执行类消息的分组（工具调用 + FlowAgent），自动提取 `userMessageTitle` |
+| isShareMode      | `ShallowRef<boolean>`         | 是否处于分享模式                                                            |
+| isAllSelected    | `ComputedRef<boolean>`        | 所有用户消息组是否全部选中                                                  |
+| onToggleShareAll | `(checked: boolean) => void`  | 切换全选                                                                    |
+| onCancelShare    | `() => void`                  | 取消分享模式                                                                |
+| onConfirmShare   | `() => Message[]`             | 确认分享，返回选中的消息数组                                                |
+
+## 类型定义
+
+```typescript
+import { type MessageGroup } from '@blueking/chat-x';
+
+interface MessageGroup {
+  uuid: string;
+  type: MessageRole;
+  messages: Message[];
+  checked: boolean;
+  isHover: boolean;
+  pause?: boolean;
+  startTime?: number;
+  userMessageTitle?: number | string;
+}
+```
+
+## 关联组件
+
+- [ChatContainer](../components/molecular/chat-container.md) — 调用 useMessageGroup 并下传分组
+- [MessageContainer](../components/molecular/message-container.md) — 渲染 messageGroups
+- [ExecutionSummary](../components/molecular/execution-summary.md) — 消费 executionGroups