@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

package/skills/blueking-chat-x/references/composables/use-global-config.md

@@ -0,0 +1,155 @@
+# useGlobalConfig
+
+> 导入：`import { useGlobalConfig } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>、timezone?: ComputedRef<string | undefined>、menuSources?: ComputedRef<IInputMenuItem[]>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size、supportUpload、timezone 与 menuSources； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。
+
+**关联**：chat-container（根容器调用 useGlobalConfig 注入 supportUpload）、message-time（消息时间组件读取 timezone）
+
+---
+
+# useGlobalConfig 全局配置
+
+> **分类**：composable
+
+在聊天容器根组件与子组件之间通过 Vue `provide` / `inject` 共享**全局展示相关配置**（当前包括字号主题档位 `size`、是否支持上传 `supportUpload`、消息时间时区 `timezone`、输入框菜单数据源 `menuSources`）。与 Teleport 插槽 ID 无关。
+
+> 字号主题主要通过 `ChatContainer` 根节点的 `data-ai-size` 与 CSS 变量（`--ai-font-size` 等）生效；`GlobalConfig.size` 供后代在逻辑层读取当前档位，样式层无需逐组件传参。
+
+## 工作原理
+
+```
+ChatContainer（根）
+  ├── :data-ai-size="size"（CSS 变量作用域）
+  ├── useGlobalConfig({
+  │     size: computed(() => props.size ?? 'small'),
+  │     supportUpload: computed(() => props.supportUpload ?? false),
+  │     timezone: computed(() => props.timezone),
+  │     menuSources: resolvedMenuSources,
+  │   })
+  │     └── provide(GLOBAL_CONFIG_TOKEN, { size, supportUpload, timezone, menuSources })
+  │
+  └── MessageContainer → … → UserMessage / MessageTime 等
+
+UserMessage（后代）
+  ├── injectGlobalConfig()
+  │     └── inject(GLOBAL_CONFIG_TOKEN) → GlobalConfig | undefined
+  └── 模板中：globalConfig?.supportUpload.value ?? false
+```
+
+- **Provider**：必须在组件树的祖先（如 `ChatContainer`）的 `setup` 中调用 `useGlobalConfig`，否则后代 `injectGlobalConfig()` 得到 `undefined`。
+- **Consumer**：任意后代在 `setup` 中调用 `injectGlobalConfig()`，拿到与 Provider 相同的 `GlobalConfig` 对象引用；`supportUpload` 为 `ComputedRef<boolean>`，可随根 props 响应式更新。
+
+## 渲染示例
+
+## 根容器用法（ChatContainer）
+
+```vue
+<script setup lang="ts">
+  import { computed } from 'vue';
+  import { useGlobalConfig } from '@blueking/chat-x';
+
+  const props = defineProps<{
+    size?: 'normal' | 'small';
+    supportUpload?: boolean;
+    timezone?: string;
+  }>();
+
+  useGlobalConfig({
+    size: computed(() => props.size ?? 'small'),
+    supportUpload: computed(() => props.supportUpload ?? false),
+    // 无默认值：未配置时由 MessageTime 回退到浏览器时区
+    timezone: computed(() => props.timezone),
+  });
+</script>
+```
+
+## 子组件用法（UserMessage）
+
+```vue
+<script setup lang="ts">
+  import { injectGlobalConfig } from '@blueking/chat-x';
+
+  const globalConfig = injectGlobalConfig();
+</script>
+
+<template>
+  <ChatInput :support-upload="globalConfig?.supportUpload.value ?? false" />
+</template>
+```
+
+## API
+
+### 类型与函数签名（摘要）
+
+```typescript
+import type { ComputedRef } from 'vue';
+
+export const GLOBAL_CONFIG_TOKEN: unique symbol;
+
+export type AiSizeMode = 'normal' | 'small';
+
+export type GlobalConfig = {
+  size?: ComputedRef<AiSizeMode>;
+  supportUpload: ComputedRef<boolean>;
+  timezone?: ComputedRef<string | undefined>;
+  /** 输入框菜单数据源；消息编辑态的内嵌输入框据此渲染 @ / \ 与 + 号菜单 */
+  menuSources?: ComputedRef<IInputMenuItem[]>;
+};
+
+export function useGlobalConfig(options: GlobalConfig): {
+  size?: ComputedRef<AiSizeMode>;
+  supportUpload: ComputedRef<boolean>;
+  timezone?: ComputedRef<string | undefined>;
+  menuSources?: ComputedRef<IInputMenuItem[]>;
+};
+
+export function injectGlobalConfig(): GlobalConfig | undefined;
+```
+
+### `GLOBAL_CONFIG_TOKEN`
+
+| 名称                  | 说明                                   |
+| --------------------- | -------------------------------------- |
+| `GLOBAL_CONFIG_TOKEN` | `provide` / `inject` 使用的 Symbol key |
+
+### `GlobalConfig`
+
+| 字段            | 说明                                                                     |
+| --------------- | ------------------------------------------------------------------------ |
+| `size`          | 可选。字号主题档位 `normal`（14px）/ `small`（12px），与 `ChatContainer.size` 对齐 |
+| `supportUpload` | 是否支持上传，与根容器 `ChatContainer` 的 `supportUpload` 等展示策略对齐 |
+| `menuSources`   | 可选。输入框菜单数据源，供消息编辑态的内嵌 `ChatInput` 使用 |
+| `timezone`      | 可选。消息时间展示所用的 IANA 时区名，与 `ChatContainer.timezone` 对齐；未配置时 `MessageTime` 按浏览器时区展示 |
+| `menuSources`   | 可选。输入框菜单数据源，与 `ChatInput.menuSources` 同源（`ChatContainer` 传入的是补齐会话产物后的结果）；[UserMessage](../components/message/user-message) 编辑态据此渲染菜单，未配置时编辑态无菜单 |
+
+### `useGlobalConfig(options)`
+
+| 参数                    | 说明                                                                                  |
+| ----------------------- | ------------------------------------------------------------------------------------- |
+| `options.size`          | 可选。字号主题档位，建议使用 `computed(() => props.size ?? 'small')` 与根 props 同步 |
+| `options.supportUpload` | 是否支持上传，建议使用 `computed(() => props.supportUpload ?? false)` 与根 props 同步 |
+| `options.timezone`      | 可选。消息时间时区，建议使用 `computed(() => props.timezone)` 与根 props 同步；不设默认值，交由 `MessageTime` 回退浏览器时区 |
+
+- 调用后立即 `provide(GLOBAL_CONFIG_TOKEN, options)`。
+- 必须在具有组件实例上下文的 `setup` 中调用（与 Vue `provide` 要求一致）。
+
+### `injectGlobalConfig()`
+
+| 返回值         | 说明                                                        |
+| -------------- | ----------------------------------------------------------- |
+| `GlobalConfig` | 祖先已调用 `useGlobalConfig` 时，与 Provider 传入的同一对象 |
+| `undefined`    | 组件树中无对应 `provide` 时                                 |
+
+## 注意事项
+
+1. **Provider 须在祖先调用**：子组件的 `injectGlobalConfig` 依赖同一组件树内的 `useGlobalConfig`。
+2. **可选链访问**：无 Provider 时返回 `undefined`，模板中建议使用 `globalConfig?.supportUpload.value ?? false`。
+3. **扩展配置**：后续若在 `GlobalConfig` 中增加字段，应在根容器统一传入并在文档中说明。
+
+## 关联组件
+
+- [ChatContainer](../components/setup/chat-container) — 调用 `useGlobalConfig` 注入 `size`、`supportUpload`、`timezone` 与 `menuSources`
+- [UserMessage](../components/message/user-message) — 编辑态读取 `supportUpload` 与 `menuSources`
+- [MessageTime](../components/feedback/message-time) — 读取 `timezone` 展示消息时间
+- [主题配置](../theme/theme) — `data-ai-size` 与 CSS 变量说明

package/skills/blueking-chat-x/references/composables/use-input-mention.md

@@ -0,0 +1,115 @@
+# useInputMention
+
+> 导入：`import { useInputMentionConsumer, useInputMentionProvider } from '@blueking/chat-x'` ｜ since 0.0.51
+
+useInputMentionProvider 由持有输入框的容器（ChatContainer）提供 insertMention， useInputMentionConsumer 在任意后代取出；无 Provider（只读 / 分享态）时返回 undefined，调用方据此隐藏「引用」入口。 消息区文件卡片与侧栏产物面板即用它把文件以标签形式追加进输入框。 源码位置：src/composables/use-input-mention.ts。
+
+**关联**：chat-container（根容器提供 insertMention，内部转发给 ChatInput 实例）、chat-input（实际执行插入的组件，expose insertMention）、file-artifact-panel（侧栏产物面板据此展示「引用」按钮）、assistant-message（消息内文件卡片据此展示「引用」按钮）
+
+---
+
+# useInputMention 资源插入输入框
+
+> **分类**：composable
+
+把「把某个资源 `@` 进输入框」这件事从组件层级里解耦出来：消息区的文件卡片、侧栏的产物面板可能嵌套得很深，逐层透传输入框实例既啰嗦又容易漏。
+
+## 工作原理
+
+```
+ChatContainer（根）
+  ├── useInputMentionProvider({
+  │     insertMention: item => chatInputRef.value?.insertMention?.(item),
+  │   })
+  │     └── provide(INPUT_MENTION_TOKEN, context)
+  │
+  ├── ChatInput（ref="chatInputRef"）
+  │     └── expose insertMention → AiSlashInput.appendMention（追加到文档末尾）
+  │
+  └── MessageContainer → … → ArtifactFileCard / FileArtifactPanel
+        └── useInputMentionConsumer() → InputMentionContext | undefined
+              └── 有值才渲染「引用」按钮
+```
+
+无 Provider 时 `useInputMentionConsumer()` 返回 `undefined`，因此只读 / 分享态（没有输入框）自动不显示引用入口，不需要额外开关。
+
+## 消费方用法
+
+```vue
+<template>
+  <span
+    v-if="inputMention"
+    v-tippy="{ content: t('引用') }"
+    @click.stop="handleCite"
+  >
+    <CiteIcon />
+  </span>
+</template>
+
+<script setup lang="ts">
+  import { toArtifactMenuItem, useInputMentionConsumer } from '@blueking/chat-x';
+
+  const props = defineProps<{ file: AIFileInfo }>();
+
+  // 无输入框上下文时为 undefined，据此隐藏入口
+  const inputMention = useInputMentionConsumer();
+
+  const handleCite = () => {
+    inputMention?.insertMention(toArtifactMenuItem(props.file));
+  };
+</script>
+```
+
+::: warning id 必须与菜单一致
+把文件转成菜单条目时统一走 [`toArtifactMenuItem`](/utils/#会话产物收集)：`id` 不一致会导致 `@` 菜单的去重与已插入标签的匹配同时失效（同一个文件既能重复插入、又无法从候选中剔除）。
+:::
+
+## 自建容器用法
+
+不使用 [ChatContainer](/components/setup/chat-container)、自行组合 `MessageContainer` + `ChatInput` 时，需要自己提供上下文：
+
+```vue
+<script setup lang="ts">
+  import { useTemplateRef } from 'vue';
+  import { ChatInput, useInputMentionProvider } from '@blueking/chat-x';
+
+  const chatInputRef = useTemplateRef<InstanceType<typeof ChatInput>>('chatInputRef');
+
+  useInputMentionProvider({
+    insertMention: item => chatInputRef.value?.insertMention?.(item),
+  });
+</script>
+```
+
+## API
+
+```typescript
+export const INPUT_MENTION_TOKEN: unique symbol;
+
+export type InputMentionContext = {
+  /** 把一个条目以标签形式追加到输入框，效果等同于用户通过 `@` 菜单选中它 */
+  insertMention: (item: IInputMenuItem) => void;
+};
+
+export function useInputMentionProvider(context: InputMentionContext): InputMentionContext;
+
+export function useInputMentionConsumer(): InputMentionContext | undefined;
+```
+
+| 函数                        | 说明                                                                   |
+| --------------------------- | ---------------------------------------------------------------------- |
+| `useInputMentionProvider`   | 在祖先 `setup` 中调用，`provide` 上下文并原样返回，便于就地复用         |
+| `useInputMentionConsumer`   | 在任意后代 `setup` 中调用，无 Provider 时返回 `undefined`               |
+
+## 注意事项
+
+1. **插入位置不依赖光标**：底层走 `AiSlashInput.appendMention`，标签追加到文档末尾——外部调用时编辑器通常没有焦点，依赖光标会插错位置。
+2. **插入的资源可能不在 `menuSources` 里**：`ChatInput` 的 `update:modelValue` 第二参数只回传能在 `menuSources` 中反查到的条目。`ChatContainer` 会自动收集消息里的会话产物，所以经容器使用时产物标签能被反查到。
+3. **必须在 `setup` 中调用**：与 Vue `provide` / `inject` 的要求一致。
+
+## 关联组件
+
+- [ChatContainer](../components/setup/chat-container) — 默认的 Provider
+- [ChatInput](../components/input/chat-input) — `insertMention` 的实际执行者
+- [FileArtifactPanel](../components/message/file-artifact-panel) — 侧栏产物面板的引用入口
+- [Utils 工具函数](../utils/) — `collectMessageArtifacts` / `toArtifactMenuItem`

package/skills/blueking-chat-x/references/composables/use-menu-keydown.md

@@ -0,0 +1,161 @@
+# useMenuKeydown
+
+> 导入：`import { useMenuKeydown } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useMenuKeydown 接收 items、menuRef、onSelect，在 window 捕获阶段监听 keydown；菜单不可见（offsetParent 为空）或列表为空时不响应。 维护 activeIndex，处理 ArrowUp/ArrowDown 循环与 Enter 选中，并 scrollIntoView 当前 .is-active 项。 InputMenuPanel（输入框统一菜单）与 ModelSelectorPanel（模型下拉）内部使用。
+
+**关联**：input-menu-panel（输入框菜单的键盘导航）、model-selector（模型下拉的键盘导航）
+
+---
+
+# 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>
+```
+
+## 库内部的实际用法
+
+`useMenuKeydown` 被 [InputMenuPanel](/components/input/input-menu-panel)（输入框统一菜单）与 [ModelSelector](/components/input/model-selector) 的下拉面板内部使用：
+
+```typescript
+// InputMenuPanel 中：items 为跨分组扁平化后的可选条目
+const panelRef = useTemplateRef<HTMLElement>('panelRef');
+const flatItems = computed(() => props.flatItems);
+const { activeIndex } = useMenuKeydown<IInputMenuItem>({
+  items: flatItems, // ComputedRef 也可传入
+  onSelect: item => emit('select', item),
+  menuRef: panelRef,
+});
+
+// 结果集变化后旧的高亮下标已无意义，回到首项
+watch(flatItems, () => {
+  activeIndex.value = 0;
+});
+```
+
+## 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/input/chat-input) — `@` 菜单与 `/` 提示词列表

package/skills/blueking-chat-x/references/composables/use-message-group.md

@@ -0,0 +1,244 @@
+# useMessageGroup
+
+> 导入：`import { useMessageGroup } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useMessageGroup 接收 keyword、messages、selectedUserMessages，通过 watchEffect 产出 messageGroups（User/Assistant/Tool 合并、末尾 Loading 注入且占位 id 为 LOADING_MESSAGE_ID、pause 与分享勾选等）。 executionGroups 供侧边执行摘要过滤，并暴露 isShareMode、全选与 onConfirmShare。 ChatContainer 组装后传给 MessageContainer；ExecutionSummary 消费 executionGroups。
+
+**关联**：chat-container（调用并传入 MessageContainer）、message-container（必填 messageGroups 数据源）、execution-summary（使用 executionGroups 与定位）
+
+---
+
+# useMessageGroup 消息分组
+
+> **分类**：composable
+
+核心消息分组逻辑，将原始 `Message[]` 数组转换为结构化的 `MessageGroup[]`。处理 Tool 消息合并、Loading 自动注入、执行摘要过滤和消息多选/分享等逻辑。
+
+## 函数签名
+
+```typescript
+function useMessageGroup(options: {
+  keyword?: ShallowRef<string>;
+  messages: ComputedRef<Message[]>;
+  renderMode?: MaybeRef<RenderMode>;
+  selectedUserMessages: Ref<Message[] | undefined>;
+}): {
+  messageGroups: Ref<MessageGroup[]>;
+  executionGroups: ComputedRef<MessageGroup[]>;
+  sessionArtifacts: ComputedRef<SessionArtifact[]>;
+  pendingApprovalCount: ComputedRef<number>;
+  pendingApprovalTipText: ComputedRef<string>;
+  isShareMode: ShallowRef<boolean>;
+  isAllSelected: ComputedRef<boolean>;
+  onToggleShareAll: (isAllSelected: boolean) => void;
+  onCancelShare: () => void;
+  onConfirmShare: () => Message[];
+};
+```
+
+## 分组规则
+
+`watchEffect` 遍历 `messages` 数组，按以下规则分组：
+
+**消息 `uid`：** 若某条消息缺少 `uid`，分组前会自动为其生成并写入 `uid`（与 `MessageGroup.uid` 及 DOM 定位约定配合）。
+
+```
+messages 原始数组（按顺序处理）
+         │
+    ┌────┴────┐────────────┐
+    │         │            │
+role=user  role=tool     其他 role
+    │         │            │
+ ① 将累积的    ② 通过          ③ 累积到
+ assistant     toolCallId     assistantMessages
+ 消息推入       找到对应的      等待 user 消息
+ list 作为      Assistant       触发分组
+ 一组，当前     消息，注入
+ user 单独      toolMessage
+ 成组           后 continue
+
+④ 遍历结束后将剩余 assistantMessages 推入 list
+⑤ 末尾为 user 消息 → 追加 Loading 消息组（`renderMode` 为 `Share` 时不追加）
+```
+
+注入的占位 Loading 消息使用固定 id：`LOADING_MESSAGE_ID`（`'__loading__'`，定义于 `common/constants`）。`ChatContainer` 据此判断是否在「请求中」阶段，并向 `ChatInput` / `MessageContainer` 下传 `MessageStatus.Fetching`，与流式中的停止、防重复发送行为对齐。
+
+### Tool 消息处理
+
+`role: 'tool'` 消息不会独立渲染，而是通过 `toolCallId` 注入到对应 AssistantMessage 的 `toolCall.toolMessage` 字段：
+
+```typescript
+const assistantToolMessage = messages.find(
+  m => m.role === 'assistant' && m.toolCalls?.some(t => t.id === message.toolCallId),
+) as AssistantMessage | undefined;
+if (assistantToolMessage) {
+  const toolCall = assistantToolMessage.toolCalls?.find(t => t.id === message.toolCallId);
+  if (toolCall) {
+    toolCall.toolMessage = message;
+  }
+  // error 时强制 assistant 为 Error；否则保留原 status，空值兜底 Complete
+  assistantToolMessage.status = message.error
+    ? MessageStatus.Error
+    : assistantToolMessage.status || MessageStatus.Complete;
+}
+```
+
+若找不到对应 `toolCall`（例如数据不一致），**跳过注入**，避免非空断言导致的运行时异常。
+
+### 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`                             |
+
+## sessionArtifacts 会话级文件产物
+
+`sessionArtifacts` 收集当前会话具有 `outputId` 的助手产物与用户上传附件，供 `ChatContainer` 侧栏「文件产物」Tab 聚合预览。以 **`outputId`** 为会话内唯一键去重（同 `outputId` 视为同一文件），保留最后一次出现的文件信息，列表顺序与「最后一次出现」的相对顺序一致：
+
+```typescript
+const sessionArtifacts = computed(() => {
+  // delete + set：同 key 覆盖内容，并把该项挪到 Map 末尾，保证「最后出现」顺序
+  const byOutputId = new Map();
+  for (const message of messages.value) {
+    for (const file of getMessageArtifacts(message)) {
+      if (byOutputId.has(file.outputId)) {
+        byOutputId.delete(file.outputId);
+      }
+      byOutputId.set(file.outputId, file);
+    }
+  }
+  return Array.from(byOutputId.values());
+});
+```
+
+> `SessionArtifact` 即为 `AIFileInfo` 别名；文件名可能重复，不可作唯一键。
+
+预览命中与取链见 [useArtifactPreview](./use-artifact-preview)；侧栏列表与分类型预览（`ArtifactPreviewHost`）见 [FileArtifactPanel](../components/message/file-artifact-panel)。
+
+## 待审批统计
+
+`useMessageGroup` 会统计消息列表中处于待审批状态的 AI Dev 审批中断：
+
+```typescript
+const pendingApprovalStatusSet = new Set([APPROVAL_STATUS.PENDING, APPROVAL_STATUS.DRAFT]);
+```
+
+当 `MessageRole.Interrupt` 消息的 `content.outcome.type === 'interrupt'`，且其中断项满足 `reason === InterruptReason.AIDevToolApproval`、`metadata.ticket.status` 为 `pending` 或 `draft` 时，计入 `pendingApprovalCount`。
+
+`pendingApprovalTipText` 根据数量生成输入区提示文案：
+
+```typescript
+'当前会话有 {count} 个待审批单，如需继续，请先取消审批'
+```
+
+`ChatContainer` 会消费该返回值，向 `ChatInput` 传入 `sendDisabledTip` 并在输入区上方展示提示，从而阻止继续发送。
+
+## 分享模式
+
+`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,
+  pendingApprovalCount,
+  pendingApprovalTipText,
+  isShareMode,
+  isAllSelected,
+  onToggleShareAll,
+  onCancelShare,
+  onConfirmShare,
+} = useMessageGroup({
+  keyword,
+  messages,
+  selectedUserMessages,
+});
+```
+
+## 返回值说明
+
+| 属性/方法名      | 类型                          | 说明                                                                        |
+| ---------------- | ----------------------------- | --------------------------------------------------------------------------- |
+| messageGroups    | `Ref<MessageGroup[]>`         | 完整消息分组列表                                                            |
+| executionGroups  | `ComputedRef<MessageGroup[]>` | 仅包含执行类消息的分组（工具调用 + FlowAgent），自动提取 `userMessageTitle` |
+| sessionArtifacts | `ComputedRef<SessionArtifact[]>` | 收集助手产物与具有 `outputId` 的上传附件，按 `outputId` 去重（保留最后一次） |
+| pendingApprovalCount | `ComputedRef<number>`      | 当前消息中待审批 AI Dev 审批中断的数量                                      |
+| pendingApprovalTipText | `ComputedRef<string>`    | 待审批阻塞发送提示文案；无待审批时为空字符串                                |
+| isShareMode      | `ShallowRef<boolean>`         | 是否处于分享模式                                                            |
+| isAllSelected    | `ComputedRef<boolean>`        | 所有用户消息组是否全部选中                                                  |
+| onToggleShareAll | `(checked: boolean) => void`  | 切换全选                                                                    |
+| onCancelShare    | `() => void`                  | 取消分享模式                                                                |
+| onConfirmShare   | `() => Message[]`             | 确认分享，返回选中的消息数组                                                |
+
+## 类型定义
+
+```typescript
+import { type MessageGroup } from '@blueking/chat-x';
+
+interface MessageGroup {
+  uid: string;
+  type: MessageRole;
+  messages: Message[];
+  checked: boolean;
+  isHover: boolean;
+  pause?: boolean;
+  startTime?: number;
+  userMessageTitle?: number | string;
+}
+```
+
+## 关联组件
+
+- [ChatContainer](../components/setup/chat-container) — 调用 useMessageGroup 并下传分组
+- [MessageContainer](../components/setup/message-container) — 渲染 messageGroups
+- [ExecutionSummary](../components/agent/execution-summary) — 消费 executionGroups