@blueking/chat-x 0.0.45-beta.6 → 0.0.45-dev.1

package/dist/mcp/generated/docs/knowledge-rag-content.md

@@ -0,0 +1,126 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+渲染知识召回活动，包含加载态、Markdown 内容与引用来源。 源码位置：src/components/chat-content/knowledge-rag-content/knowledge-rag-content.vue。
+
+### 关联组件
+- **activity-message** — activityType 为 knowledge_rag 时分发到本组件
+- **activity-layout** — 提供可折叠的活动容器外壳
+- **markdown-content** — 渲染知识召回摘要正文
+- **reference-content** — 渲染召回引用来源列表
+
+---
+<!-- FULL DOC -->
+
+# KnowledgeRagContent 知识召回内容
+
+> **能力域**：Agent 能力
+
+`KnowledgeRagContent` 用于渲染知识召回活动内容，包含活动标题、加载态、Markdown 摘要和引用来源列表。它是 `ActivityMessage` 在 `activityType === 'knowledge_rag'` 时使用的具体内容组件。
+
+通常不需要直接使用，`MessageRender -> ActivityMessage` 会根据消息类型自动分发到本组件。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/knowledge-rag-content/knowledge-rag-content.vue`
+- **能力说明**：渲染知识召回活动，包含加载态、Markdown 内容与引用来源。
+
+## 核心能力
+
+- **活动外壳**：基于 `ActivityLayout` 渲染可折叠活动区域，默认展开
+- **状态标题**：`status` 为 `pending` / `streaming` 时标题显示“检索中”并展示 Loading；其他状态显示“检索完成”
+- **Markdown 摘要**：使用 `MarkdownContent` 渲染 `content.content`
+- **引用来源**：使用 `ReferenceContent` 渲染 `content.referenceDocument`
+- **空值兜底**：正文缺失时传入空字符串，引用缺失时传入空数组
+
+## 基础用法
+
+```vue
+<template>
+  <KnowledgeRagContent
+    v-model:collapsed="collapsed"
+    :content="content"
+    status="complete"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import KnowledgeRagContent from '@blueking/chat-x/src/components/chat-content/knowledge-rag-content/knowledge-rag-content.vue';
+  import type { KnowledgeRagMessageContent } from '@blueking/chat-x';
+
+  const collapsed = ref(false);
+
+  const content: KnowledgeRagMessageContent = {
+    content: '根据知识库检索，**蓝鲸智云** 常见 Agent 接入流程包括...',
+    referenceDocument: [
+      { name: 'Agent 接入指南', url: 'https://example.com/agent-guide', originFile: 'https://example.com/docs/agent-guide' },
+    ],
+  };
+</script>
+```
+
+**渲染效果**
+
+## 检索中状态
+
+当消息状态为 `pending` 或 `streaming` 时，标题区域显示 Loading，标题文案为“检索中”。
+
+## 折叠状态
+
+`collapsed` 通过 `v-model:collapsed` 与 `ActivityLayout` 双向绑定，适合由父级活动消息统一控制展开/收起。
+
+## API
+
+### Props
+
+| 属性名     | 类型                         | 必填 | 默认值 | 说明                                     |
+| ---------- | ---------------------------- | ---- | ------ | ---------------------------------------- |
+| content    | `KnowledgeRagMessageContent` | 否   | —      | 知识召回摘要与引用来源                   |
+| messageUid | `string`                     | 否   | —      | 所属消息唯一标识，当前组件暂未直接使用   |
+| status     | `MessageStatus`              | 否   | —      | 消息状态，影响标题文案与 Loading 显示    |
+
+### Models
+
+| 名称      | 类型      | 默认值  | 说明             |
+| --------- | --------- | ------- | ---------------- |
+| collapsed | `boolean` | `false` | 活动内容是否折叠 |
+
+### Emits
+
+- 无显式 emits；`v-model:collapsed` 会产生 `update:collapsed`。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 类型定义
+
+```typescript
+export type KnowledgeRagMessageContent = {
+  content: string;
+  referenceDocument: ReferenceDocumentContent[];
+};
+
+export type ReferenceDocumentContent = {
+  name: string;
+  originFile: string;
+  url: string;
+};
+```
+
+## 使用建议
+
+- 业务接入时优先通过 [ActivityMessage](../message/activity-message.md) 或完整消息链路使用，避免重复判断 `activityType`。
+- `referenceDocument` 为空时组件仍会渲染正文区域，引用列表由 `ReferenceContent` 处理空数组。
+
+## 关联组件
+
+- [ActivityMessage](../message/activity-message.md) — 活动消息分发入口。
+- [ActivityLayout](../helper/activity-layout.md) — 折叠活动外壳。
+- [MarkdownContent](../rendering/markdown-content.md) — Markdown 摘要渲染。
+- [ReferenceContent](../rendering/reference-content.md) — 引用来源列表。

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-LatexContent 使用 KaTeX 渲染 math_block / math_inline 等 token，支持行内块级混排与流式防抖。 必填 props 为 token 数组；失败时静默降级展示原始 LaTeX 文本。 由 MarkdownContent 在数学插件解析后自动调用。
+使用 KaTeX 渲染 LaTeX 公式内容。 源码位置：src/components/markdown-token/latex-content/latex-content.vue。
 
 ### 关联组件
 - **markdown-content** — 插件解析 $...$ / $$...$$ 后生成数学 token 并挂载本组件
@@ -10,10 +10,15 @@ LatexContent 使用 KaTeX 渲染 math_block / math_inline 等 token，支持行
 <!-- FULL DOC -->
 
 # LatexContent LaTeX 公式渲染
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：内容渲染
+- **源码位置**：`src/components/markdown-token/latex-content/latex-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：使用 KaTeX 渲染 LaTeX 公式内容。
 
-Markdown Token 层的 LaTeX 公式渲染原子组件，基于 **KaTeX** 实现。被 `MarkdownContent` 在解析到数学公式 token 时自动调用，通常无需手动引入。
+> **能力域**：内容渲染
+
+Markdown Token 层的 LaTeX 公式渲染基础组件，基于 **KaTeX** 实现。被 `MarkdownContent` 在解析到数学公式 token 时自动调用，通常无需手动引入。
 
 核心能力：**流式防抖渲染**（throttle 100ms）、**语法自动补全**（`completeLatexContent`）、**渐进式降级重试**（最多 5 次）、**错误静默**（错误文本白色不可见）。
 
@@ -193,4 +198,4 @@ const displayMode = token.type === 'math_block' || token.meta?.displayMode === t
 
 ## 关联组件
 
-- [MarkdownContent](./markdown-content.md) — 数学公式 token 的来源与挂载
+- [MarkdownContent](/components/rendering/markdown-content) — 数学公式 token 的来源与挂载

package/dist/mcp/generated/docs/loading-message.md

@@ -1,19 +1,24 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-LoadingMessage 展示等待 AI 响应的加载动画（内部 AiLoading），无必填 Props，默认插槽可自定义「请求中」文案。 典型用法是由 MessageContainer 在末尾为用户消息时自动注入 Loading 组；也可在自定义布局中手动放置。
+消息列表中的加载占位，默认使用 AiLoading，也支持默认插槽覆盖。 源码位置：src/components/chat-message/loading-message/loading-message.vue。
 
 ### 关联组件
 - **message-container** — 在消息列表末尾自动追加 Loading 消息组
 - **message-render** — role 为 loading 时由 MessageRender 渲染
-- **ai-loading** — 内部使用 AiLoading 原子组件
+- **ai-loading** — 内部使用 AiLoading 基础组件
 
 ---
 <!-- FULL DOC -->
 
 # LoadingMessage 加载中消息
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：消息展示
+- **源码位置**：`src/components/chat-message/loading-message/loading-message.vue`
+- **能力域**：消息系统
+- **能力说明**：消息列表中的加载占位，默认使用 AiLoading，也支持默认插槽覆盖。
+
+> **能力域**：消息系统
 
 加载等待状态组件，展示 AI 正在处理请求时的过渡动画。由旋转渐变环 + 脉冲星形图标（蓝→紫→粉渐变）和"请求中..."文案组成。支持通过默认插槽自定义加载文案。
 
@@ -166,6 +171,6 @@ enum MessageRole {
 
 ## 关联组件
 
-- [MessageContainer](./message-container.md) — 自动注入加载组
-- [MessageRender](./message-render.md) — loading 角色派发
-- [AiLoading](../atomic/ai-loading.md) — 内部动画组件
+- [MessageContainer](/components/setup/message-container) — 自动注入加载组
+- [MessageRender](/components/message/message-render) — loading 角色派发
+- [AiLoading](/components/helper/ai-loading) — 内部动画组件

package/dist/mcp/generated/docs/markdown-container.md

@@ -53,4 +53,4 @@ const md = new MarkdownIt({ html: true }).use(markdownItContainer, /^hljs-(left|
 
 ## 关联
 
-- [MarkdownContent](../components/atomic/markdown-content.md) — 实际接入与样式
+- [MarkdownContent](../components/rendering/markdown-content) — 实际接入与样式

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-MarkdownContent 将 Markdown 字符串解析为 token 并渲染，集成代码块、公式、Mermaid 等子渲染器。 核心 props 为 content 与 status；内置流式节流、语法补全与 DOMPurify 安全策略。 通常由 ContentRender、AssistantMessage 等间接使用，无需业务直接挂载。
+Markdown 主渲染器，集成代码块、公式、错误降级和 codeHeader 插槽。 源码位置：src/components/chat-content/markdown-content/markdown-content.vue。
 
 ### 关联组件
 - **code-content** — fence 代码块语法高亮与复制
@@ -13,12 +13,17 @@ MarkdownContent 将 Markdown 字符串解析为 token 并渲染，集成代码
 <!-- FULL DOC -->
 
 # MarkdownContent Markdown 内容渲染
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：内容渲染
+- **源码位置**：`src/components/chat-content/markdown-content/markdown-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：Markdown 主渲染器，集成代码块、公式、错误降级和 codeHeader 插槽。
 
-AI 消息内容渲染的核心原子组件，集成代码高亮、LaTeX 公式、Mermaid 图表等能力，内置流式渲染优化（5ms throttle + 语法补全 + 防闪烁）。
+> **能力域**：内容渲染
 
-由 `AssistantMessage`、`ReasoningMessage` 等分子组件内部自动使用，通常不需要手动引入。
+AI 消息内容渲染的核心基础组件，集成代码高亮、LaTeX 公式、Mermaid 图表等能力，内置流式渲染优化（5ms throttle + 语法补全 + 防闪烁）。
+
+由 `AssistantMessage`、`ReasoningMessage` 等组合组件内部自动使用，通常不需要手动引入。
 
 ## 组件结构与渲染流程
 
@@ -225,7 +230,7 @@ const domPurifyConfig = {
 
 ## 关联组件
 
-- [CodeContent](./code-content.md) — 代码 fence 高亮
-- [LatexContent](./latex-content.md) — 公式渲染
-- [MermaidContent](./mermaid-content.md) — Mermaid 图表
-- [ContentRender](../molecular/content-render.md) — 内容类型分发入口
+- [CodeContent](/components/rendering/code-content) — 代码 fence 高亮
+- [LatexContent](/components/rendering/latex-content) — 公式渲染
+- [MermaidContent](/components/rendering/mermaid-content) — Mermaid 图表
+- [ContentRender](/components/rendering/content-render) — 内容类型分发入口

package/dist/mcp/generated/docs/markdown-latex.md

@@ -203,6 +203,6 @@ KaTeX 限制：
 
 ## 关联组件
 
-- [LatexContent](../components/atomic/latex-content.md) — KaTeX 渲染
-- [MarkdownContent](../components/atomic/markdown-content.md) — Markdown 内容
-- [ContentRender](../components/molecular/content-render.md) — 内容渲染
+- [LatexContent](../components/rendering/latex-content) — KaTeX 渲染
+- [MarkdownContent](../components/rendering/markdown-content) — Markdown 内容
+- [ContentRender](../components/rendering/content-render) — 内容渲染

package/dist/mcp/generated/docs/markdown-mermaid.md

@@ -245,6 +245,6 @@ erDiagram
 
 ## 关联组件
 
-- [MermaidContent](../components/atomic/mermaid-content.md) — Mermaid 渲染
-- [MarkdownContent](../components/atomic/markdown-content.md) — Markdown 内容
-- [ContentRender](../components/molecular/content-render.md) — 内容渲染
+- [MermaidContent](../components/rendering/mermaid-content) — Mermaid 渲染
+- [MarkdownContent](../components/rendering/markdown-content) — Markdown 内容
+- [ContentRender](../components/rendering/content-render) — 内容渲染

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-MermaidContent 将 info 为 mermaid 的 fence token 渲染为 SVG，模块级懒加载单例 Mermaid。 具备流式 throttle、错误静默与 SVG ID 随机化，避免多实例冲突。 由 MarkdownContent 在解析 mermaid 代码块时调用。
+渲染 Mermaid 图表并处理渲染事件。 源码位置：src/components/markdown-token/mermaid-content/mermaid-content.vue。
 
 ### 关联组件
 - **markdown-content** — 解析 mermaid 类型 fence 代码块后传入 token
@@ -10,10 +10,15 @@ MermaidContent 将 info 为 mermaid 的 fence token 渲染为 SVG，模块级懒
 <!-- FULL DOC -->
 
 # MermaidContent Mermaid 图表渲染
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：内容渲染
+- **源码位置**：`src/components/markdown-token/mermaid-content/mermaid-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：渲染 Mermaid 图表并处理渲染事件。
 
-Markdown Token 层的 Mermaid 图表渲染原子组件，被 `MarkdownContent` 在检测到 mermaid fence token 时自动调用，通常无需手动引入。
+> **能力域**：内容渲染
+
+Markdown Token 层的 Mermaid 图表渲染基础组件，被 `MarkdownContent` 在检测到 mermaid fence token 时自动调用，通常无需手动引入。
 
 核心能力：**按需懒加载 Mermaid**（动态 import 单例）、**三级去重跳过**（代码比对 → 语法校验 → SVG 比对）、**100ms throttle** 流式防抖、**错误静默**（parse 失败时保持上一次 SVG）。
 
@@ -182,4 +187,4 @@ mermaid.default.render('mermaid-content-' + Math.random().toString(36).substring
 
 ## 关联组件
 
-- [MarkdownContent](./markdown-content.md) — mermaid fence token 的来源与挂载
+- [MarkdownContent](/components/rendering/markdown-content) — mermaid fence token 的来源与挂载

package/dist/mcp/generated/docs/message-container.md

@@ -1,19 +1,25 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-MessageContainer 是消息列表的核心容器。接收父组件用 useMessageGroup 生成的 messageGroups 与 messageStatus， 内部通过 MessageRender 按组渲染消息。支持流式停止、自动滚动与返回底部、多选与工具栏，需配置 onAgentAction 处理复制/重试等；点赞点踩通过 onAgentFeedback 回传原因。通常与 ChatInput 组合成完整对话区。
+负责消息分组渲染、滚动控制、工具栏和消息插槽透传。 源码位置：src/components/chat-message/message-container/message-container.vue。
 
 ### 关联组件
 - **message-render** — 按组渲染每条消息时委托 MessageRender
 - **chat-input** — 常与 ChatInput 组合构成完整对话界面
 - **loading-message** — 末尾为用户消息时自动追加 Loading 消息组
+- **interrupt-message** — 透传 onInterruptResume；末条 interrupt 消息不触发组 hover
 
 ---
 <!-- FULL DOC -->
 
 # MessageContainer 消息容器
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：消息展示
+- **源码位置**：`src/components/chat-message/message-container/message-container.vue`
+- **能力域**：对话搭建
+- **能力说明**：负责消息分组渲染、滚动控制、工具栏和消息插槽透传。
+
+> **能力域**：对话搭建
 
 消息列表容器组件，负责将原始的 `Message[]` 数组渲染为结构化的对话界面。核心能力：
 
@@ -113,6 +119,7 @@ MessageContainer 是消息列表的核心容器。接收父组件用 useMessageG
 - 每个消息组外层 DOM 的 `id` 为 **`MessageGroup.uid`**（由 `useMessageGroup` 生成），供执行摘要「在对话中定位」、侧栏自定义 Tab 等场景滚动锚定
 - `role: 'tool'` 消息**不会独立渲染**，而是被注入到对应 AssistantMessage 的 `toolCall.toolMessage` 字段
 - 若 `toolMessage.error` 存在，AssistantMessage 的 `status` 会被强制设为 `MessageStatus.Error`
+- 当消息组**最后一条**消息的 `role === 'interrupt'` 时，`mouseenter` **不会**设置 `isHover`，避免 AI 工具栏在审批卡片上误显
 - `MessageTools` 工具栏只在 `type === 'assistant'` 的消息组底部渲染（不依赖鼠标悬停，始终可见），且满足以下条件时**不渲染**：
   - `renderMode === RenderMode.Share`（分享预览模式）
   - 消息组的 `pause` 为 `true`（来源于 `message.property?.extra?.pause`）
@@ -356,9 +363,42 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 
 **渲染效果**（点击 Checkbox 体验多选）
 
+## 自定义消息组渲染
+
+使用 `#group` 插槽可替换单个消息组的默认内容（Checkbox、消息列表、`MessageTools`）。外层 `.message-group` 容器（含 `id`、hover 状态、选中背景色）仍由 `MessageContainer` 管理。
+
+> **注意**：提供 `#group` 后需自行编排组内全部 UI；若只需替换单条消息，请使用 `#default` 插槽。
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :message-groups="messageGroups"
+    message-status="complete"
+    :on-agent-action="handleAgentAction"
+    @stop-streaming="handleStopStreaming"
+  >
+    <template #group="{ group }">
+      <div class="custom-group">
+        <span class="custom-group-label">{{ group.type }}</span>
+        <div
+          v-for="message in group.messages"
+          :key="message.id"
+          class="custom-group-message"
+        >
+          {{ typeof message.content === 'string' ? message.content : JSON.stringify(message.content) }}
+        </div>
+      </div>
+    </template>
+  </MessageContainer>
+</template>
+```
+
+**渲染效果**（简化自定义组布局，不含默认 Checkbox 与工具栏）
+
 ## 自定义消息渲染
 
-使用默认插槽替换单条消息的渲染，插槽参数包含 `message` 和 `messageToolsStatus`：
+使用默认插槽替换单条消息的渲染，插槽参数包含 `message`、`messageToolsStatus` 和 `onInterruptResume`：
 
 ```vue
 <template>
@@ -369,10 +409,11 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
     :on-user-action="handleUserAction"
     @stop-streaming="handleStopStreaming"
   >
-    <template #default="{ message, messageToolsStatus }">
+    <template #default="{ message, messageToolsStatus, onInterruptResume }">
       <MyCustomMessage
         :message="message"
         :message-tools-status="messageToolsStatus"
+        :on-interrupt-resume="onInterruptResume"
       />
     </template>
   </MessageContainer>
@@ -468,6 +509,7 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 | onUserAction             | `(tool: IToolBtn, message: Message) => Promise<string[] \| void>`                            | —       | 用户消息工具操作回调                                                                                                                     |
 | onUserInputConfirm       | `(message: Message, content: UserMessage['content'], docSchema: TagSchema) => Promise<void>` | —       | 用户编辑消息确认回调                                                                                                                     |
 | onUserShortcutConfirm    | `(message: Message, formModel: Record<string, unknown>) => Promise<void>`                    | —       | 用户快捷指令表单提交回调                                                                                                                 |
+| onInterruptResume        | `OnInterruptResume`                                                                          | —       | AG-UI human-in-the-loop 中断响应回调，透传给 `MessageRender` → `InterruptMessageRender`                                                  |
 | renderMode               | `RenderMode`                                                                                 | —       | 渲染模式。`Share` 模式下启用多选样式并隐藏工具栏；`Test` 模式下过滤掉「分享」按钮；不传或 `Chat` 为默认行为                              |
 
 ### v-model
@@ -484,14 +526,28 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 
 ### Slots
 
-| 插槽名  | 参数                                                                        | 说明                                             |
-| ------- | --------------------------------------------------------------------------- | ------------------------------------------------ |
-| default | `{ message: Message, messageToolsStatus: MessageToolsStatus \| undefined }` | 自定义单条消息渲染，消息分组和工具栏仍由容器管理 |
+| 插槽名           | 参数                                                                                                        | 说明                                                                                     |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| answeredQuestion | `{ item, index, status }`                                                                                   | 自定义 UserQuestion 已回答回显，透传给 MessageRender → InterruptMessageRender            |
+| default          | `{ message: Message, messageToolsStatus?: MessageToolsStatus, onInterruptResume?: OnInterruptResume }`     | 自定义单条消息渲染；消息分组外层容器与 `#group` 未覆盖时的工具栏仍由容器管理             |
+| group            | `{ group: MessageGroup }`                                                                                   | 自定义单个消息组内容，替换默认 Checkbox、消息列表与 `MessageTools`；外层组容器仍由组件管理 |
 
 ## 类型定义
 
 ```typescript
-import { MessageRole, MessageStatus, MessageToolsStatus, type Message, type IToolBtn } from '@blueking/chat-x';
+import { MessageRole, MessageStatus, MessageToolsStatus, type Message, type MessageGroup, type IToolBtn } from '@blueking/chat-x';
+
+// 消息组（由 useMessageGroup 生成，也可手动传入 messageGroups）
+interface MessageGroup {
+  checked: boolean;
+  isHover: boolean;
+  messages: Message[];
+  pause?: boolean;
+  startTime?: number;
+  type: MessageRole;
+  uid: string;
+  userMessageTitle?: number | string;
+}
 
 // onAgentAction 回调类型
 // messages 为当前消息组全部消息（可含 reasoning / activity 等）
@@ -518,6 +574,7 @@ enum MessageRole {
   Reasoning = 'reasoning',
   Activity = 'activity',
   Info = 'info',
+  Interrupt = 'interrupt',
   Loading = 'loading',
 }
 
@@ -534,6 +591,7 @@ enum MessageStatus {
 
 ## 关联组件
 
-- [MessageRender](./message-render.md) — 按组渲染每条消息时委托使用
-- [ChatInput](./chat-input.md) — 常与输入区组合构成完整对话界面
-- [LoadingMessage](./loading-message.md) — 末尾为用户消息时自动追加加载组
+- [MessageRender](/components/message/message-render) — 按组渲染每条消息时委托使用
+- [InterruptMessage 中断消息](/components/agent/interrupt-message) — `role: 'interrupt'` 的渲染与 `onInterruptResume` 透传
+- [ChatInput](/components/input/chat-input) — 常与输入区组合构成完整对话界面
+- [LoadingMessage](/components/message/loading-message) — 末尾为用户消息时自动追加加载组

package/dist/mcp/generated/docs/message-loading.md

@@ -0,0 +1,120 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+带品牌图标和逐字渐变动画的加载组件。 源码位置：src/components/message-loading/message-loading.vue。
+
+### 关联组件
+- **loading-message** — 消息列表加载占位可选择使用品牌加载动效
+- **ai-loading** — 更轻量的三点加载动画
+
+---
+<!-- FULL DOC -->
+
+# MessageLoading 品牌加载
+
+> **能力域**：辅助能力
+
+`MessageLoading` 是带蓝鲸品牌图标和逐字渐变动画的加载组件，用于展示 AI 正在思考、生成或执行任务的等待状态。组件默认显示品牌图标和“加载中...”文案，也支持通过插槽替换图标或文本。
+
+与 [AiLoading](./ai-loading.md) 相比，它更偏品牌化、文案化；适合较明显的等待区域，不适合嵌入很紧凑的按钮或状态点。
+
+## 源码事实
+
+- **源码位置**：`src/components/message-loading/message-loading.vue`
+- **能力说明**：带品牌图标和逐字渐变动画的加载组件。
+
+## 核心能力
+
+- **品牌图标动画**：默认使用 `AIBluekingIcon`，图标随 `duration` 做透明度和滤镜动画
+- **逐字渐变文本**：未传 `#text` 插槽时，将 `text` 拆成字符逐个渲染，并按 `stagger` 延迟播放
+- **可调尺寸和节奏**：通过 `iconSize`、`gap`、`duration`、`stagger` 控制图标尺寸、间距和动画速度
+- **插槽覆盖**：`#icon` 可替换图标，`#text` 可替换整段文本渲染
+- **无障碍降级**：遵循 `prefers-reduced-motion: reduce`，减少动画效果
+
+## 基础用法
+
+```vue
+<template>
+  <MessageLoading />
+</template>
+
+<script setup lang="ts">
+  import { MessageLoading } from '@blueking/chat-x';
+</script>
+```
+
+**渲染效果**
+
+## 自定义文案和尺寸
+
+```vue
+<template>
+  <MessageLoading
+    text="正在思考中..."
+    :icon-size="28"
+    :gap="10"
+    :duration="2"
+    :stagger="0.12"
+  />
+</template>
+```
+
+## 自定义插槽
+
+传入 `#text` 后，组件不再按字符拆分 `text` prop，而是直接渲染插槽内容；传入 `#icon` 可替换默认品牌图标。
+
+```vue
+<template>
+  <MessageLoading>
+    <template #icon>
+      <span class="custom-icon">AI</span>
+    </template>
+    <template #text>
+      正在生成巡检结论
+    </template>
+  </MessageLoading>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型     | 必填 | 默认值      | 说明                               |
+| -------- | -------- | ---- | ----------- | ---------------------------------- |
+| text     | `string` | 否   | `'加载中...'` | 逐字动画文案；使用 `#text` 时可不传 |
+| iconSize | `number` | 否   | `32`        | 默认图标边长，单位 px              |
+| gap      | `number` | 否   | `8`         | 图标与文字间距，单位 px            |
+| duration | `number` | 否   | `1.8`       | 单次动画循环时长，单位秒           |
+| stagger  | `number` | 否   | `0.135`     | 相邻字符动画延迟，单位秒           |
+
+### Emits
+
+- 无。
+
+### Slots
+
+| 插槽名 | 说明                     |
+| ------ | ------------------------ |
+| icon   | 自定义图标区域           |
+| text   | 自定义文本区域，覆盖逐字渲染 |
+
+### Expose
+
+- 无。
+
+## 样式与 attrs
+
+- 组件设置 `inheritAttrs: false`，会将外部 `class` 合并到根节点，并将除 `class` / `style` 外的 attrs 透传到根节点。
+- 外部对象形式的 `style` 会与 CSS 变量合并；字符串形式 `style` 不会参与合并。
+- 根节点使用 CSS 变量控制动画：`--ai-message-loading-duration`、`--ai-message-loading-stagger`、`--ai-message-loading-gap`。
+
+## 使用建议
+
+- 页面级或消息级等待态优先使用 `MessageLoading`；紧凑状态点优先使用 [AiLoading](./ai-loading.md)。
+- 需要自定义文本样式时优先使用 `#text` 插槽，避免只依赖全局覆盖内部 class。
+
+## 关联组件
+
+- [LoadingMessage](../message/loading-message.md) — 消息列表中的加载占位。
+- [AiLoading](./ai-loading.md) — 三点加载动画。