@blueking/chat-x 0.0.43 → 0.0.45-beta.2

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-AssistantMessage 渲染 AI 助手回复：正文由 ContentRender（可被默认插槽替换）与 ToolCallRender 展示工具调用及 MCP 标记。 toolCalls[].toolMessage 可内联工具执行结果。用于 MessageRender 分发的 assistant 角色，流式场景配合 streaming 状态更新。
+渲染助手消息主体、工具调用与文件内容，默认插槽可覆盖正文渲染。 源码位置：src/components/chat-message/assistant-message/assistant-message.vue。
 
 ### 关联组件
 - **message-render** — 由 MessageRender 在 role 为 assistant 时创建
@@ -12,8 +12,13 @@ AssistantMessage 渲染 AI 助手回复：正文由 ContentRender（可被默认
 <!-- FULL DOC -->
 
 # AssistantMessage AI 助手消息
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：消息展示
+- **源码位置**：`src/components/chat-message/assistant-message/assistant-message.vue`
+- **能力域**：消息系统
+- **能力说明**：渲染助手消息主体、工具调用与文件内容，默认插槽可覆盖正文渲染。
+
+> **能力域**：消息系统
 
 AI 助手消息展示组件，负责渲染 AI 回复的文本内容和工具调用（Tool Calls）结果。
 
@@ -419,6 +424,6 @@ interface ToolMessage extends BaseMessage<MessageRole.Tool, string> {
 
 ## 关联组件
 
-- [MessageRender](./message-render.md) — assistant 角色由其实例化
-- [ToolMessage](./tool-message.md) — 工具执行结果可通过 toolCall.toolMessage 内联
-- [ToolcallRender](./toolcall-render.md) — 工具调用列表渲染
+- [MessageRender](/components/message/message-render) — assistant 角色由其实例化
+- [ToolMessage](/components/message/tool-message) — 工具执行结果可通过 toolCall.toolMessage 内联
+- [ToolcallRender](/components/agent/toolcall-render) — 工具调用列表渲染

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ChatContainer 提供完整 AI 对话布局：分栏（ResizeLayout）、消息列表（MessageContainer）、输入（ChatInput）、执行摘要（ExecutionSummary）、快捷表单（ShortcutRender）与多选栏（SelectionFooter）。 内置 useMessageGroup、分享与自定义 Tab 等能力；对 MessageContainer/ChatInput 下推 inputStatus（末尾 Loading 占位时推导 Fetching），适合一站式接入。 通过 props 传入 messages、shortcuts 等，事件与 ChatInput/MessageContainer 对齐；renderMode 会通过内部 provide 下传给子内容组件。
+完整对话容器，组合消息列表、输入区、快捷指令、执行摘要、分享选择和自定义 Tab。 源码位置：src/components/chat-container/chat-container.vue。
 
 ### 关联组件
 - **message-container** — 消息列表与滚动区域
@@ -14,18 +14,24 @@ ChatContainer 提供完整 AI 对话布局：分栏（ResizeLayout）、消息
 <!-- FULL DOC -->
 
 # ChatContainer 聊天容器
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：输入交互
+- **源码位置**：`src/components/chat-container/chat-container.vue`
+- **能力域**：对话搭建
+- **能力说明**：完整对话容器，组合消息列表、输入区、快捷指令、执行摘要、分享选择和自定义 Tab。
+
+> **能力域**：对话搭建
 
 顶层聊天容器组件，整合了 `MessageContainer`（消息列表）、`ChatInput`（输入框）、`ExecutionSummary`（执行摘要面板）、`ShortcutRender`（快捷指令表单）和 `SelectionFooter`（多选操作栏）。提供完整的 AI 对话界面布局能力。
 
 ## 核心能力
 
-- **分栏布局**：基于 `ResizeLayout` 的可拖拽分栏；**侧栏是否展示 Tab / 执行摘要、以及分栏是否进入折叠样式（`ai-is-collapse`）以 `executionGroups` 与执行情况搜索关键词 `keyword` 共同决定**（`executionGroups` 由 `useMessageGroup` 从消息中过滤工具调用与 FlowAgent 记录；`keyword` 来自 `ExecutionSummary` 的 `@update-keyword`）。当 `executionGroups` 为空且未输入搜索词时，侧栏 Tab 与执行摘要不展示；**用户正在搜索执行情况时（`keyword` 非空），即使暂无执行类消息也会保留侧栏**，避免搜索态被折叠
+- **分栏布局**：基于 `ResizeLayout` 的可拖拽分栏；**侧栏是否展示 Tab / 执行摘要、以及分栏是否进入折叠样式（`ai-is-collapse`）以 `executionGroups` 为准**（由 `useMessageGroup` 从消息中过滤出工具调用与 FlowAgent 执行记录），**不以原始 `messages.length` 判断**。因此仅有普通对话、尚无执行类消息时，侧栏内容与「执行情况」区域可能为空，布局上与无执行数据时一致
 - **消息分组**：内置 `useMessageGroup` 自动处理消息分组、Tool 合并、Loading 注入
 - **输入区状态推导**：传给 `MessageContainer` 与 `ChatInput` 的 `messageStatus` 为内部计算值 `inputStatus`：当分组中存在 id 为 `LOADING_MESSAGE_ID`（`'__loading__'`，由 `useMessageGroup` 注入的占位 Loading 消息）时，对内使用 `MessageStatus.Fetching`；否则使用外部传入的 `messageStatus`。用于在「已发用户消息、尚未流式」阶段与流式中一致地展示停止能力，并避免输入区重复发送
+- **待审批发送阻塞**：当消息中存在 `AIDevToolApproval` 且状态为 `pending` / `draft` 的中断项时，`useMessageGroup` 会返回待审批提示，容器在输入区上方展示提示并通过 `ChatInput.sendDisabledTip` 禁止继续发送
+- **用户问题中断**：当消息中存在待回答 `UserQuestion` 中断时，容器会在输入区上方挂载 `UserQuestionCard`；若配置了 `onInterruptResume`，用户也可直接在输入框输入自由文本并作为 Others 回答 resume
 - **执行摘要**：侧边栏展示工具调用 / FlowAgent 执行记录，支持关键词搜索和对话定位
-- **侧栏全屏**：Tab 栏右侧提供全屏/退出全屏按钮，基于 `useFullScreen` 将侧栏区域（`.ai-full-screen-wrapper`）以浏览器原生全屏展示；全屏时 Tippy 的 `appendTo` 自动切换为全屏容器，避免 tooltip 被遮挡
 - **自定义 Tab**：通过 `useCustomTabProvider` 支持动态添加自定义 Tab（如节点详情）
 - **分享模式**：内置消息多选分享流程，选中用户消息后确认分享
 - **渲染模式注入**：`renderMode` 会通过内部 Provider 下传给后代内容组件；例如 FlowAgent 节点在 `Share` 模式下隐藏耗时和「详情」入口
@@ -38,22 +44,22 @@ ai-chat-container
 ├── Loading（chatLoading 时）
 └── ResizeLayout
     ├── aside（侧边栏）
-    │   ├── .ai-full-screen-wrapper（全屏目标容器，ref=fullScreenRef）
-    │   │   ├── Tab 标签页
-    │   │   │   ├── 执行情况（默认 Tab）
-    │   │   │   ├── 自定义 Tab × N（可关闭；标签可由 `getSideTabRenderComponent` 自定义）
-    │   │   │   └── #setting 插槽 → 全屏/退出全屏 ToolBtn（FullScreenIcon / UnFullScreenIcon）
-    │   │   ├── ExecutionSummary（执行情况 Tab 内容）
-    │   │   └── 自定义 Tab 组件（`getSideRenderComponent` 优先，否则 `data.component`；可向子组件注入 #locateButton）
-    │   └── collapse-button（折叠按钮，CollapsedIcon；折叠时图标旋转，hover 高亮 #3a84ff）
+    │   ├── Tab 标签页
+    │   │   ├── 执行情况（默认 Tab）
+    │   │   └── 自定义 Tab × N（可关闭）
+    │   ├── ExecutionSummary（执行情况 Tab 内容）
+    │   ├── 自定义 Tab 组件（通过 component :is 渲染，可向子组件注入 #locateButton）
+    │   └── collapse-button（折叠按钮）
     └── main（主内容区）
         ├── MessageContainer（有消息时）
+        │   ├── #group 插槽（可选，自定义消息组内容）
+        │   ├── #message 插槽（可选，自定义单条消息）
         │   └── 消息列表 + 工具栏
         ├── 欢迎页（无消息时，容器 .ai-welcome-content）
         │   └── welcome 插槽（默认：Banner + 欢迎标题 + 开场白 ContentRender；自定义则整块替换）
         ├── SelectionFooter（分享模式时）
         ├── ShortcutRender（有快捷指令时）
-        └── ChatInput（默认状态）
+        └── ChatInput（默认状态，待审批时通过 interrupt slot 展示 InputInfoAlert）
 ```
 
 ## 基础用法
@@ -112,9 +118,9 @@ ai-chat-container
 
 侧边栏默认包含「执行情况」Tab，展示所有工具调用和 FlowAgent 类型的 Activity 消息。支持关键词搜索过滤和点击定位到对话中的消息位置。
 
-**展示条件**：当 `executionGroups` 为空且 `keyword` 为空时，不渲染侧栏 Tab 与 `ExecutionSummary`（折叠按钮亦隐藏）；主区域仍可正常展示 `messages` 中的对话内容。用户在执行情况中输入搜索词后，侧栏会保持展示以显示「搜索结果为空」等状态。`renderMode === Share` 时侧栏隐藏，且分栏会应用与折叠一致的样式。
+**展示条件**：当 `executionGroups` 为空时，不渲染侧栏 Tab 与 `ExecutionSummary`（折叠按钮亦隐藏）；主区域仍可正常展示 `messages` 中的对话内容。`renderMode === Share` 时侧栏隐藏，且分栏会应用与折叠一致的样式。
 
-**自定义 Tab 联动**：当 `executionGroups` 变为空且搜索词已清空时，容器会**自动重置自定义 Tab**（`resetCustomTab`），避免残留节点详情等 Tab；若用户仍在搜索（`keyword` 非空），不会触发重置。
+**自定义 Tab 联动**：当 `executionGroups` 变为空（例如会话清空或仅剩无执行类消息）时，容器会**自动重置自定义 Tab**（`resetCustomTab`），避免残留节点详情等 Tab。
 
 ```vue
 <template>
@@ -141,72 +147,20 @@ ai-chat-container
 
 侧边栏放置方向通过 `placement` 控制：
 
-| `placement` | 侧边栏位置   | 折叠按钮位置 | 折叠图标旋转 |
-| ----------- | ------------ | ------------ | ------------ |
-| `left`      | 左侧（默认） | 主区域左边缘 | 折叠时旋转 180° |
-| `right`     | 右侧         | 主区域右边缘 | 默认旋转 180°，折叠时恢复 0° |
-
-> 折叠按钮仅展示 `CollapsedIcon`（不再显示「执行情况」文案），通过图标旋转方向指示展开/折叠状态。
+| `placement` | 侧边栏位置   | 折叠按钮位置 |
+| ----------- | ------------ | ------------ |
+| `left`      | 左侧（默认） | 主区域左边缘 |
+| `right`     | 右侧         | 主区域右边缘 |
 
 **placement 对比**（左右两种布局）
 
-## 侧栏全屏
-
-当侧栏 Tab 区域可见时，Tab 栏右侧（`#setting` 插槽）内置全屏切换按钮：
-
-- 点击 **全屏** 图标：调用 `useFullScreen(fullScreenRef).enter()`，将 `.ai-full-screen-wrapper` 进入浏览器原生全屏
-- 点击 **退出全屏** 图标：调用 `exit()` 退出；用户按 ESC 退出时 `isFullScreen` 也会自动同步
-- 全屏状态下，侧栏内 `v-overflow-tips` 的 `appendTo` 会指向全屏容器，避免 tooltip 挂载到 `document.body` 后被全屏层遮挡
-
-该能力由内部 `useFullScreen` composable 提供，详见 [useFullScreen](../../composables/use-full-screen.md)。
-
 ## 自定义 Tab
 
-通过 `ref` 获取组件实例后，使用 `addCustomTab` / `removeCustomTab` 动态管理侧边栏 Tab。若 **`executionGroups` 变为空且搜索词已清空**，容器会清空自定义 Tab 状态（与侧栏执行数据联动，见上文「侧边栏与执行摘要」）。
-
-### 侧栏渲染扩展
-
-应用层可通过以下 Props 覆盖默认 Tab 标签与侧栏内容区的渲染逻辑（例如 FlowAgent 节点详情使用业务自定义组件）：
-
-| Prop | 说明 |
-| ---- | ---- |
-| `getSideTabRenderComponent` | `(h, tab, { removeCustomTab }) => VNode \| undefined`。返回自定义 Tab 标签 VNode；未返回时使用默认图标 + `tab.label` + 关闭按钮 |
-| `getSideRenderComponent` | `(h, props) => VNode \| undefined`。返回侧栏内容区组件 VNode；未返回时使用 `selectedTab.data.component` |
-
-侧栏内容区实现上会以 **`selectedTab.name` 作为外层 `key`**，切换 Tab 时重建子树，避免插槽与局部状态残留；当前 Tab 的 `:is` 由内部 **`computed`** 根据 `getSideRenderComponent(h, selectedTab.data.props)` 与 `data.component` 解析，保证 Tab 切换或 `onCustomTabChange` 异步更新 props 后内容类型与数据一致。
-
-```vue
-<template>
-  <ChatContainer
-    :get-side-tab-render-component="renderSideTab"
-    :get-side-render-component="renderSidePanel"
-    ...
-  />
-</template>
-
-<script setup lang="ts">
-  import { h } from 'vue';
-  import type { CustomTab } from '@blueking/chat-x';
-
-  const renderSideTab = (createElement, tab, { removeCustomTab }) => {
-    if (tab.name.startsWith('custom-')) {
-      return createElement('span', {}, tab.label);
-    }
-    return undefined; // 走默认 Tab 标签
-  };
-
-  const renderSidePanel = (createElement, props) => {
-    if (props?.has_confidence) {
-      return createElement(MyConfidencePanel, props);
-    }
-    return undefined; // 走 tab.data.component
-  };
-</script>
-```
+通过 `ref` 获取组件实例后，使用 `addCustomTab` / `removeCustomTab` 动态管理侧边栏 Tab。若 **`executionGroups` 变为空**，容器会清空自定义 Tab 状态（与侧栏执行数据联动，见上文「侧边栏与执行摘要」）。
 
 ### 自定义 Tab 与「在对话中定位」
 
-`addCustomTab` 的 `data` 可携带 **`messageUid`**（与对应活动消息的 `message.uid` 一致）。`ChatContainer` 在侧栏用 `<component :is="sideRenderComponent">`（内部计算属性，见上文「侧栏渲染扩展」）渲染自定义 Tab 时，会向子组件提供 **`locateButton` 插槽**：默认渲染「在对话中定位」按钮，点击后调用内部 `handleLocateMessageGroup(messageUid)`，优先滚动到主区域 `document.getElementById(messageUid)`；若不存在该节点，则在当前 `messageGroups` 中查找包含 `message.uid === messageUid` 的消息组，并滚动到该组的容器（`MessageGroup.uid` 作为组级 `id`）。
+`addCustomTab` 的 `data` 可携带 **`messageUid`**（与对应活动消息的 `message.uid` 一致）。`ChatContainer` 在侧栏用 `<component :is>` 渲染自定义 Tab 时，会向子组件提供 **`locateButton` 插槽**：默认渲染「在对话中定位」按钮，点击后调用内部 `handleLocateMessageGroup(messageUid)`，优先滚动到主区域 `document.getElementById(messageUid)`；若不存在该节点，则在当前 `messageGroups` 中查找包含 `message.uid === messageUid` 的消息组，并滚动到该组的容器（`MessageGroup.uid` 作为组级 `id`）。
 
 子组件若需展示该按钮，请在模板中声明 `<slot name="locateButton" />`（例如 FlowAgent 节点详情标题栏）。`FlowAgentContent` 等会在打开节点详情 Tab 时将 `messageUid` 写入 `data`，与 `ActivityMessage` 下传给内容区的 `message-uid` 对齐。
 
@@ -317,6 +271,93 @@ ai-chat-container
 
 `messageStatus` 为 `streaming` 时，底部固定区域显示「停止生成」按钮，点击后触发 `@stop-streaming` 事件：
 
+## 待审批阻塞发送
+
+当会话中存在待审批的 AI Dev 工具审批中断时，`ChatContainer` 会在输入框上方展示提示，并禁用发送按钮。用户需要在审批卡片中点击「取消审批」或等待状态变化后，才能继续发送新消息。
+
+```vue
+<template>
+  <ChatContainer
+    v-model="inputValue"
+    :messages="messages"
+    message-status="complete"
+    :on-interrupt-resume="handleInterruptResume"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+  />
+</template>
+```
+
+**渲染效果**（待审批单存在时，输入区上方展示提示，发送按钮置灰）
+
+## 用户问题中断
+
+当会话中最近一条待处理 interrupt 包含 `InterruptReason.UserQuestion` 时，`ChatContainer` 会在 `ChatInput` 上方显示 [UserQuestionCard](/components/agent/user-question-card)。用户完成或跳过后通过 `onInterruptResume(payload, interrupt)` 通知业务侧继续 Agent。
+
+```vue
+<template>
+  <ChatContainer
+    v-model="inputValue"
+    :messages="messages"
+    message-status="complete"
+    :on-interrupt-resume="handleInterruptResume"
+    :on-send-message="handleSendMessage"
+  />
+</template>
+
+<script setup lang="ts">
+  import { type OnInterruptResume } from '@blueking/chat-x';
+
+  const handleInterruptResume: OnInterruptResume = async (payload, interrupt) => {
+    // UserQuestion 完成时 payload 为 UserQuestionResume
+    // 自由文本输入也会转换为 label: 'others' 的单条回答
+    await resumeAgent({ interruptId: interrupt.id, resume: payload });
+  };
+</script>
+```
+
+如果没有传入 `onInterruptResume`，输入框自由文本不会被中断逻辑截获，仍然走普通 `onSendMessage`，避免输入被静默清空。
+
+## 自定义消息组渲染
+
+通过 `#group` 插槽可替换单个消息组的默认内容，透传至内部 `MessageContainer`。外层消息组容器（`id`、hover、选中背景）仍由 `MessageContainer` 管理。
+
+> **注意**：提供 `#group` 后需自行编排组内全部 UI（Checkbox、消息列表、`MessageTools`）；若只需替换单条消息，请使用 `#message` 插槽。详见 [MessageContainer 自定义消息组渲染](/components/setup/message-container#自定义消息组渲染)。
+
+```vue
+<ChatContainer
+  v-model="inputValue"
+  :messages="messages"
+  message-status="complete"
+  :on-send-message="handleSendMessage"
+>
+  <template #group="{ group }">
+    <MyCustomGroup :group="group" />
+  </template>
+</ChatContainer>
+```
+
+### 自定义题目渲染
+
+通过 `#interruptQuestion` slot 可覆盖输入区上方 `UserQuestionCard` 的默认选择题渲染，参数与 [UserQuestionCard](/components/agent/user-question-card) 的 `#question` 一致：
+
+```vue
+<ChatContainer
+  v-model="inputValue"
+  :messages="messages"
+  :on-interrupt-resume="handleInterruptResume"
+  :on-send-message="handleSendMessage"
+>
+  <template #interruptQuestion="{ question, qIndex, answer, setAnswer, confirm }">
+    <MyCustomForm
+      :model="question"
+      @change="setAnswer"
+      @submit="confirm"
+    />
+  </template>
+</ChatContainer>
+```
+
 ## 分享模式
 
 点击消息工具栏的「分享」按钮后进入分享模式，底部出现 `SelectionFooter` 操作栏：
@@ -394,16 +435,14 @@ ChatContainer 的 Props 继承自 `ChatInputProps` 和 `MessageContainerProps`
 
 | 属性名             | 类型                                                                         | 默认值   | 说明                                                                                                                                          |
 | ------------------ | ---------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| chatLoading                 | `boolean`                                                                    | —        | 整体加载状态，`true` 时显示 Loading 遮罩                                                                                                      |
-| commonTippyOptions          | `AITippyProps`                                                               | —        | 通用 Tippy 配置（`appendTo` / `placement` / `zIndex`），传入的选项会注入到所有使用 `v-overflow-tips` 的子组件中                                 |
-| getSideRenderComponent      | `(h, props?) => VNode \| undefined`                                          | —        | 自定义侧栏内容区渲染；未返回时使用 `selectedTab.data.component`                                                                               |
-| getSideTabRenderComponent   | `(h, tab, { removeCustomTab }) => VNode \| undefined`                        | —        | 自定义侧栏 Tab 标签渲染；未返回时使用默认图标 + 文案 + 关闭按钮                                                                               |
-| openingRemark               | `string`                                                                     | —        | 开场白，无消息时显示，支持 Markdown                                                                                                           |
+| chatLoading        | `boolean`                                                                    | —        | 整体加载状态，`true` 时显示 Loading 遮罩                                                                                                      |
+| commonTippyOptions | `AITippyProps`                                                               | —        | 通用 Tippy 配置，传入的选项会注入到所有使用 `v-overflow-tips` 的子组件中                                                                      |
+| openingRemark      | `string`                                                                     | —        | 开场白，无消息时显示，支持 Markdown                                                                                                           |
 | placement          | `'left' \| 'right'`                                                          | `'left'` | 侧边栏位置                                                                                                                                    |
 | resizeProps        | `{ disabled?: boolean; initialDivide?: number \| string; max?: number; min?: number }` | —        | 透传给内部 `ResizeLayout` 的可选配置，与默认 `collapsible: false`、`immediate: true`、`min: 400` 合并；`placement` 始终取自本组件 `placement`；`initialDivide` 可为像素数字或百分比等字符串（与 bkui ResizeLayout 一致） |
 | onCustomTabChange  | `(tab: CustomTab) => Promise<any>`                                           | —        | 自定义 Tab 切换回调，返回值作为 Tab 组件 props                                                                                                |
 
-> 完整 Props 列表请参考 [ChatInput](./chat-input.md) 和 [MessageContainer](./message-container.md) 文档。
+> 完整 Props 列表请参考 [ChatInput](/components/input/chat-input) 和 [MessageContainer](/components/setup/message-container) 文档。
 
 ### v-model
 
@@ -428,12 +467,14 @@ ChatContainer 的 Props 继承自 `ChatInputProps` 和 `MessageContainerProps`
 
 ### Slots
 
-| 插槽名     | 参数                                   | 说明                                                                                           |
-| ---------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| codeHeader | `{ language: string; token: Token[] }` | 代码块头部自定义操作区域，透传给 MessageRender → ContentRender → MarkdownContent → CodeContent |
-| default    | 消息列表相关绑定（messages 等）        | 自定义消息列表区域                                                                             |
-| message    | `{ message, messageToolsStatus }`      | 自定义单条消息渲染                                                                             |
-| welcome    | `{ openingRemark: string }`            | 无消息时自定义欢迎页；传入则替换默认 Banner、标题与开场白区域（整块替换）                      |
+| 插槽名            | 参数                                                                                                              | 说明                                                                                           |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| codeHeader        | `{ language: string; token: Token[] }`                                                                            | 代码块头部自定义操作区域，透传给 MessageRender → ContentRender → MarkdownContent → CodeContent |
+| default           | 消息列表相关绑定（messages 等）                                                                                   | 自定义消息列表区域                                                                             |
+| group             | `{ group: MessageGroup }`                                                                                         | 自定义单个消息组内容，透传至 MessageContainer 的 `#group`；替换默认 Checkbox、消息列表与工具栏   |
+| interruptQuestion | `{ question, qIndex, answer, setAnswer, confirm }`                                                                  | 自定义 UserQuestion 单题渲染，透传至输入区上方 UserQuestionCard 的 `#question`                 |
+| message           | `{ message, messageToolsStatus, onInterruptResume }`                                                              | 自定义单条消息渲染；自定义渲染中断消息时需继续透传 `onInterruptResume`                         |
+| welcome           | `{ openingRemark: string }`                                                                                       | 无消息时自定义欢迎页；传入则替换默认 Banner、标题与开场白区域（整块替换）                      |
 
 ### Expose
 
@@ -478,7 +519,19 @@ ChatContainer 的 Props 继承自 `ChatInputProps` 和 `MessageContainerProps`
 ## 类型定义
 
 ```typescript
-import { ChatContainer, RenderMode, type CustomTab, type Shortcut, type Message } from '@blueking/chat-x';
+import { ChatContainer, RenderMode, MessageRole, type CustomTab, type MessageGroup, type Shortcut, type Message } from '@blueking/chat-x';
+
+// 消息组（由 useMessageGroup 生成）
+interface MessageGroup {
+  checked: boolean;
+  isHover: boolean;
+  messages: Message[];
+  pause?: boolean;
+  startTime?: number;
+  type: MessageRole;
+  uid: string;
+  userMessageTitle?: number | string;
+}
 
 // 自定义 Tab（data 可与 messageUid 组合，供侧栏定位主对话）
 interface CustomTab<T = Record<string, unknown>> {
@@ -497,10 +550,8 @@ interface Shortcut {
 
 ## 关联组件
 
-- [MessageContainer](./message-container.md) — 消息列表区域
-- [ChatInput](./chat-input.md) — 输入与快捷指令
-- [ShortcutRender](./shortcut-render.md) — 快捷指令表单
-- [ExecutionSummary](./execution-summary.md) — 执行摘要侧栏
-- [SelectionFooter](../atomic/selection-footer.md) — 多选操作栏
-- [ToolBtn](../atomic/tool-btn.md) — 侧栏全屏按钮（自定义插槽）
-- [useFullScreen](../../composables/use-full-screen.md) — 侧栏全屏控制
+- [MessageContainer](/components/setup/message-container) — 消息列表区域
+- [ChatInput](/components/input/chat-input) — 输入与快捷指令
+- [ShortcutRender](/components/input/shortcut-render) — 快捷指令表单
+- [ExecutionSummary](/components/agent/execution-summary) — 执行摘要侧栏
+- [SelectionFooter](/components/input/selection-footer) — 多选操作栏

package/dist/mcp/generated/docs/chat-input.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ChatInput 是聊天主输入区，集成富文本编辑（/ 提示词模板、@ 资源引用）、消息引用、附件上传与快捷指令入口。 通过 prompts、resources、shortcuts 等 props 配置能力，配合 messageStatus 控制发送、流式与停止。 内部组合 ShortcutBtns、FileUploadBtn 等，与 ShortcutRender 联动完成含表单的快捷指令流程。
+聊天输入区，组合富文本输入、快捷指令、附件、引用、发送/停止等交互。 源码位置：src/components/chat-input/chat-input.vue。
 
 ### 关联组件
 - **shortcut-btns** — 底部附件区默认展示的快捷指令列表
@@ -14,8 +14,13 @@ ChatInput 是聊天主输入区，集成富文本编辑（/ 提示词模板、@
 <!-- FULL DOC -->
 
 # ChatInput 聊天输入框
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：输入交互
+- **源码位置**：`src/components/chat-input/chat-input.vue`
+- **能力域**：输入交互
+- **能力说明**：聊天输入区，组合富文本输入、快捷指令、附件、引用、发送/停止等交互。
+
+> **能力域**：输入交互
 
 聊天消息输入框组件，支持快捷指令选择、资源 `@` 引用、Prompt `/` 模板、消息引用、文件上传（拖拽/粘贴/点击）等功能。
 
@@ -24,6 +29,7 @@ ChatInput 是聊天主输入区，集成富文本编辑（/ 提示词模板、@
 ```
 chat-input-container
 ├── slot#top（容器顶部，在输入框框体外侧）
+├── slot#interrupt（容器顶部，在输入框框体外侧，通常展示中断/审批提示）
 └── chat-input（框体，受 inputMaxHeight 控制）
     ├── slot#input-header（默认：cite 不为空时渲染引用区）
     ├── slot#files（默认：有上传文件时渲染文件预览区）
@@ -87,6 +93,28 @@ chat-input-container
 
 > **实现细节**：组件内部用 `messageState` 计算属性决定实际按钮状态：当 `messageStatus` 为 `pending`、`streaming` 或 `fetching` 时直接使用该状态（确保停止按钮始终可用）；否则当输入为空或仅含空白字符时强制为 `disabled`，其余情况使用 `messageStatus` 的值。`fetching` 时按 Enter **不会**触发发送（避免请求中与 Loading 占位阶段重复提交）。
 
+### sendDisabledTip（业务阻塞发送）
+
+当业务侧需要临时阻止发送但仍允许用户输入时，可传入 `sendDisabledTip`。组件会置灰发送按钮，按钮 tooltip 展示该文案，并拦截点击发送、按 Enter 发送和 `triggerSendMessage()`：
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    message-status="complete"
+    :send-disabled-tip="interruptTip"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+  >
+    <template #interrupt>
+      <div class="input-alert">{{ interruptTip }}</div>
+    </template>
+  </ChatInput>
+</template>
+```
+
+**渲染效果**
+
 ### Complete（可发送）
 
 ### Streaming（流式输出中，显示停止按钮）
@@ -370,11 +398,12 @@ chat-input-container
 
 ## 自定义插槽
 
-组件提供 5 个插槽用于自定义各区域内容：
+组件提供 6 个插槽用于自定义各区域内容：
 
 | 插槽名         | 位置                                       | 默认行为                                   |
 | -------------- | ------------------------------------------ | ------------------------------------------ |
 | `top`          | 框体外部顶部（`.chat-input` 上方）         | 无                                         |
+| `interrupt`    | 框体外部顶部，位于 `top` 之后              | 无，通常用于展示审批/中断提示              |
 | `input-header` | 框体内部顶部（编辑器上方）                 | `cite` 不为空时渲染引用区（`CiteContent`） |
 | `files`        | 文件预览区                                 | 有上传文件时渲染 `FileContent`             |
 | `attachment`   | 底部工具栏快捷指令区（FileUploadBtn 右侧） | 快捷指令按钮列表 / 已选快捷指令            |
@@ -393,6 +422,11 @@ chat-input-container
       <div class="input-tips">当前模型: GPT-4 · 剩余 Token: 12,800</div>
     </template>
 
+    <!-- 框体外顶部，适合展示中断、审批等业务提示 -->
+    <template #interrupt>
+      <div class="input-alert">当前会话有待审批单，暂时不能继续发送</div>
+    </template>
+
     <!-- 替换引用区，可自定义引用样式 -->
     <template #input-header>
       <div class="custom-header">自定义头部内容</div>
@@ -422,7 +456,7 @@ chat-input-container
 </template>
 ```
 
-**渲染效果**（顶部自定义模型信息提示）
+**渲染效果**（顶部自定义模型信息与中断提示）
 
 ## Expose（模板引用）
 
@@ -467,6 +501,7 @@ chat-input-container
 | placeholder        | `string`                                                                   | 见默认值 | -    | 编辑器占位符，支持多行                                  |
 | inputMaxHeight     | `number`                                                                   | `200`    | -    | 框体最大高度（px），有文件时自动加上文件预览区高度      |
 | defaultUploadFiles | `UploadFile[]`                                                             | -        | -    | 预设已上传的文件列表                                    |
+| sendDisabledTip    | `string`                                                                   | -        | -    | 业务阻塞发送时的 tooltip 提示；传入后发送按钮置灰，点击、Enter 与 `triggerSendMessage()` 均不会发送 |
 | supportUpload      | `boolean`                                                                  | `true`   | -    | 是否显示文件上传按钮                                    |
 | tippyOptions       | `AITippyProps`                                                             | —        | -    | 透传给 FileUploadBtn 和 InputAttachment 的 tooltip 配置 |
 | onSendMessage      | `(content: UserMessage['content'], docSchema: TagSchema) => Promise<void>` | -        | -    | 发送消息回调，无文件时 content 为字符串，有文件时为数组 |
@@ -494,6 +529,7 @@ chat-input-container
 | 插槽名       | 参数                               | 说明                                                       |
 | ------------ | ---------------------------------- | ---------------------------------------------------------- |
 | top          | -                                  | 框体（`.chat-input`）外部顶部，适合展示模型/Token 信息     |
+| interrupt    | -                                  | 框体外部顶部，位于 `top` 后，适合展示审批/中断提示         |
 | input-header | -                                  | 框体内顶部，替换引用区（`CiteContent`）                    |
 | files        | `{ files: Partial<UploadFile>[] }` | 文件预览区                                                 |
 | attachment   | -                                  | 底部快捷指令区，`FileUploadBtn` 在其左侧，不受此 slot 影响 |
@@ -628,8 +664,8 @@ type SendContent =
 
 ## 关联组件
 
-- [ShortcutBtns](../atomic/shortcut-btns.md) — 底部附件区默认快捷指令列表
-- [ShortcutBtn](../atomic/shortcut-btn.md) — 已选快捷指令单按钮展示
-- [ShortcutRender](./shortcut-render.md) — 含表单的快捷指令表单渲染
-- [ChatContainer](./chat-container.md) — 顶层布局中包裹输入区
-- [CiteContent](../atomic/cite-content.md) — 消息引用区内容展示
+- [ShortcutBtns](/components/input/shortcut-btns) — 底部附件区默认快捷指令列表
+- [ShortcutBtn](/components/input/shortcut-btn) — 已选快捷指令单按钮展示
+- [ShortcutRender](/components/input/shortcut-render) — 含表单的快捷指令表单渲染
+- [ChatContainer](/components/setup/chat-container) — 顶层布局中包裹输入区
+- [CiteContent](/components/rendering/cite-content) — 消息引用区内容展示

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-CiteContent 在输入区上方以紧凑条带展示被引用文本片段，单行截断并可选关闭按钮移除引用。 常与 ChatInput 的引用预览区配合，不执行 HTML 渲染。
+渲染输入或消息中的引用片段。 源码位置：src/components/chat-content/cite-content/cite-content.vue。
 
 ### 关联组件
 - **chat-input** — 输入区展示待发送引用内容
@@ -10,8 +10,13 @@ CiteContent 在输入区上方以紧凑条带展示被引用文本片段，单
 <!-- FULL DOC -->
 
 # CiteContent 引用内容
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：辅助组件
+- **源码位置**：`src/components/chat-content/cite-content/cite-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：渲染输入或消息中的引用片段。
+
+> **能力域**：内容渲染
 
 展示被引用文本片段的紧凑条带组件。固定高度 28px，左侧引用图标 + 单行截断文本 + 可选关闭图标，背景灰色（`#f5f7fa`）。
 
@@ -135,4 +140,4 @@ const message = {
 
 ## 关联组件
 
-- [ChatInput](../molecular/chat-input.md) — 引用区常见挂载位置
+- [ChatInput](/components/input/chat-input) — 引用区常见挂载位置

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-CodeContent 接收 markdown-it 的 fence/code_block token，按行 highlight.js 高亮并带语言标签与复制。 必填 props 为 token 数组；mounted 事件用于滚动联动等。 由 MarkdownContent 在解析代码块时挂载，面向流式增量更新。
+渲染 Markdown 代码块，支持高亮、复制和 header 插槽。 源码位置：src/components/markdown-token/code-content/code-content.vue。
 
 ### 关联组件
 - **markdown-content** — 解析 Markdown 后生成 fence token 并渲染本组件
@@ -10,10 +10,15 @@ CodeContent 接收 markdown-it 的 fence/code_block token，按行 highlight.js
 <!-- FULL DOC -->
 
 # CodeContent 代码块渲染
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：内容渲染
+- **源码位置**：`src/components/markdown-token/code-content/code-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：渲染 Markdown 代码块，支持高亮、复制和 header 插槽。
 
-代码块渲染原子组件，专为 **Markdown 流式输出**设计。接收 `markdown-it` token 数组，基于 `highlight.js`（github-dark 主题）实现逐行语法高亮，顶部固定深色头部展示语言名和复制按钮。
+> **能力域**：内容渲染
+
+代码块渲染基础组件，专为 **Markdown 流式输出**设计。接收 `markdown-it` token 数组，基于 `highlight.js`（github-dark 主题）实现逐行语法高亮，顶部固定深色头部展示语言名和复制按钮。
 
 ## 组件结构
 
@@ -204,4 +209,4 @@ import type { Token } from 'markdown-it';
 
 ## 关联组件
 
-- [MarkdownContent](./markdown-content.md) — 解析并传入 code fence token
+- [MarkdownContent](/components/rendering/markdown-content) — 解析并传入 code fence token

package/dist/mcp/generated/docs/common-error-content.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-CommonErrorContent 以红色错误图标加文案展示失败态，布局为 flex 横排，文本为纯文本插值。 在 MarkdownContent、ReasoningMessage 等链路上当 status 为 error 时自动替换内容区。
+展示统一错误提示内容。 源码位置：src/components/chat-content/common-error-content/common-error-content.vue。
 
 ### 关联组件
 - **markdown-content** — Markdown 渲染错误态展示
@@ -11,10 +11,15 @@ CommonErrorContent 以红色错误图标加文案展示失败态，布局为 fle
 <!-- FULL DOC -->
 
 # CommonErrorContent 通用错误内容
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：辅助组件
+- **源码位置**：`src/components/chat-content/common-error-content/common-error-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：展示统一错误提示内容。
 
-错误状态消息渲染原子组件。红色 `ErrorIcon`（14×14px，绝对定位）+ 文本区域，`display: flex` 水平排列。
+> **能力域**：内容渲染
+
+错误状态消息渲染基础组件。红色 `ErrorIcon`（14×14px，绝对定位）+ 文本区域，`display: flex` 水平排列。
 
 通常由上层组件在 `status === 'error'` 时自动渲染，无需手动使用。
 
@@ -66,5 +71,5 @@ CommonErrorContent 以红色错误图标加文案展示失败态，布局为 fle
 
 ## 关联组件
 
-- [MarkdownContent](./markdown-content.md) — Markdown 错误态
-- [ReasoningMessage](../molecular/reasoning-message.md) — 推理错误态
+- [MarkdownContent](/components/rendering/markdown-content) — Markdown 错误态
+- [ReasoningMessage](/components/message/reasoning-message) — 推理错误态