@blueking/chat-x 0.0.42 → 0.0.45-beta.1

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>
@@ -461,13 +502,14 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 | messageGroups            | `MessageGroup[]`                                                                             | —       | 预计算的消息分组；传入时跳过内部分组逻辑，由 `ChatContainer` 通过 `useMessageGroup` 提供                                                 |
 | messageStatus            | `MessageStatus`                                                                              | —       | 当前整体消息状态，控制底部「停止生成」按钮显示；`ChatContainer` 会结合末尾 Loading 占位推导 `fetching` 等再传入                                                                                                   |
 | messageToolsStatus       | `MessageToolsStatus`                                                                         | —       | 工具栏状态，透传给 `MessageTools` 和 `MessageRender`                                                                                     |
-| messageToolsTippyOptions | `AITippyProps`                                                                               | —       | 透传给 `MessageTools` 和 `MessageRender`（进而透传给 `UserMessage` 的工具栏）的 Tippy 配置，用于自定义 tooltip 挂载点、位置等（如 `appendTo`、`placement`、`zIndex`） |
+| messageToolsTippyOptions | `AITippyProps`                                                                               | —       | 透传给 `MessageTools` 和 `MessageRender`（进而透传给 `UserMessage` 的工具栏）的 Tippy 配置，用于自定义 tooltip 挂载点（如 `appendTo`）等 |
 | enableSelection          | `boolean`                                                                                    | `false` | 是否启用多选模式                                                                                                                         |
 | onAgentAction            | `(tool: IToolBtn, messages: Message[]) => Promise<string[] \| void>`                         | —       | AI 消息工具操作回调；`copy` 操作由内部处理，`like/unlike` 应返回反馈原因字符串数组                                                       |
 | onAgentFeedback          | `(tool: IToolBtn, messages: Message[], reasonList: string[], otherReason: string) => void`   | —       | AI 消息反馈提交回调（点赞/踩选完原因后触发）                                                                                             |
 | 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) — 三点加载动画。

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

@@ -1,19 +1,25 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-MessageRender 是单条消息的渲染入口，根据 message.role 派发到 UserMessage、AssistantMessage、ReasoningMessage、 ToolMessage、ActivityMessage、InfoMessage、LoadingMessage 等。Assistant 默认通过插槽用 ContentRender 渲染正文，可被默认插槽覆盖。 无独立状态，通常由 MessageContainer 内部调用而非业务直接挂载。
+按 message.role 分发到用户、助手、工具、推理、活动、中断等消息组件。 源码位置：src/components/chat-message/message-render/message-render.vue。
 
 ### 关联组件
 - **message-container** — 在 MessageContainer 中按组调用以渲染每条消息
 - **assistant-message** — role 为 assistant 时渲染 AI 回复与工具调用
 - **user-message** — role 为 user 时渲染用户消息
+- **interrupt-message** — role 为 interrupt 时渲染 InterruptMessageRender
 
 ---
 <!-- FULL DOC -->
 
 # MessageRender 消息渲染器
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：消息展示
+- **源码位置**：`src/components/chat-message/message-render/message-render.vue`
+- **能力域**：消息系统
+- **能力说明**：按 message.role 分发到用户、助手、工具、推理、活动、中断等消息组件。
+
+> **能力域**：消息系统
 
 统一的消息渲染入口，通过 `message.role` 字段自动派发到对应的子组件。整个渲染过程由一个 `computed` 属性完成，无额外状态。
 
@@ -35,6 +41,7 @@ MessageRender
 │     ├── 'tool'       → ToolMessage（转发 message）
 │     ├── 'activity'   → ActivityMessage（转发 message）
 │     ├── 'loading'    → LoadingMessage（转发 message）
+│     ├── 'interrupt'  → InterruptMessageRender（转发 message + onInterruptResume）
 │     │
 │     └── 其他 / 未知   → null（不渲染任何内容）
 ```
@@ -267,15 +274,17 @@ slot 参数类型与 `AssistantMessage` 的 slot 保持一致（`Partial<Assista
 | messageToolsStatus | `MessageToolsStatus`                                                       | —      | 工具按钮状态；**仅转发给 `UserMessage`**          |
 | onAction           | `(tool: IToolBtn) => Promise<string[] \| void>`                            | —      | 工具操作回调；**仅转发给 `UserMessage`**          |
 | onInputConfirm     | `(content: UserMessage['content'], docSchema: TagSchema) => Promise<void>` | —      | 用户编辑确认回调；**仅转发给 `UserMessage`**      |
+| onInterruptResume  | `(payload: InterruptResume, interrupt: Interrupt) => Promise<void>`        | —      | 中断响应回调；**仅转发给 `InterruptMessageRender`**     |
 | onShortcutConfirm  | `(formModel: Record<string, unknown>) => Promise<void>`                    | —      | 用户快捷指令提交回调；**仅转发给 `UserMessage`**  |
 | tippyOptions       | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | —      | 自定义 Tippy 配置；**仅转发给 `UserMessage`**     |
 
 ### Slots
 
-| 插槽名     | 参数                                         | 说明                                                                                                    |
-| ---------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| codeHeader | `{ language: string; token: Token[] }`       | 代码块头部自定义操作区域，透传给 ContentRender → MarkdownContent → CodeContent；**仅对 assistant 生效** |
-| default    | `{ content: string, status: MessageStatus }` | 替换 AssistantMessage 的内容区域渲染；**仅对 `role: 'assistant'` 生效**                                 |
+| 插槽名           | 参数                                         | 说明                                                                                                    |
+| ---------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| answeredQuestion | `{ item, index, status }`                    | 自定义 UserQuestion 已回答回显，透传给 InterruptMessageRender → UserQuestionAnsweredCard 的 `#answer`   |
+| codeHeader       | `{ language: string; token: Token[] }`       | 代码块头部自定义操作区域，透传给 ContentRender → MarkdownContent → CodeContent；**仅对 assistant 生效** |
+| default          | `{ content: string, status: MessageStatus }` | 替换 AssistantMessage 的内容区域渲染；**仅对 `role: 'assistant'` 生效**                                 |
 
 ## 消息类型映射
 
@@ -288,6 +297,7 @@ slot 参数类型与 `AssistantMessage` 的 slot 保持一致（`Partial<Assista
 | `tool`        | `ToolMessage`      | `message`                                                                                               | 工具调用返回结果      |
 | `activity`    | `ActivityMessage`  | `message`                                                                                               | 知识检索 / 引用文档   |
 | `loading`     | `LoadingMessage`   | `message`（字段被忽略，组件无 Props）                                                                   | 等待响应的加载占位    |
+| `interrupt`   | `InterruptMessageRender` | `message` + `onInterruptResume`                                                                         | human-in-the-loop 中断 |
 | 其他 / 未知   | —                  | —                                                                                                       | 返回 `null`，不渲染   |
 
 ## 类型定义
@@ -325,6 +335,8 @@ enum MessageToolsStatus {
 
 ## 关联组件
 
-- [MessageContainer](./message-container.md) — 内部按组调用以渲染每条消息
-- [AssistantMessage](./assistant-message.md) — assistant 角色派发目标
-- [UserMessage](./user-message.md) — user 角色派发目标
+- [MessageContainer](/components/setup/message-container) — 内部按组调用以渲染每条消息
+- [AssistantMessage](/components/message/assistant-message) — assistant 角色派发目标
+- [UserMessage](/components/message/user-message) — user 角色派发目标
+- [InterruptMessage 中断消息](/components/agent/interrupt-message) — interrupt 角色派发目标
+- [ToolApprovalCard 审批卡片](/components/agent/tool-approval-card) — AI Dev 审批中断子卡片

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-MessageTools 渲染 AI 消息底部工具区：左侧消息工具（复制、引用、重建等），右侧更新工具；点赞/踩会弹出 UserFeedback 收集原因。 工具 id 为 delete 时用 DeleteTool 替代普通 ToolBtn 做二次确认；其余操作通过 onAction 异步解析或直出。
+消息悬浮工具栏，组合复制、删除、反馈等工具按钮。 源码位置：src/components/message-tools/message-tools.vue。
 
 ### 关联组件
 - **tool-btn** — 普通工具项由 ToolBtn 渲染
@@ -12,8 +12,13 @@ MessageTools 渲染 AI 消息底部工具区：左侧消息工具（复制、引
 <!-- FULL DOC -->
 
 # MessageTools 消息工具栏
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：工具与反馈
+- **源码位置**：`src/components/message-tools/message-tools.vue`
+- **能力域**：工具与反馈
+- **能力说明**：消息悬浮工具栏，组合复制、删除、反馈等工具按钮。
+
+> **能力域**：工具与反馈
 
 AI 消息的操作工具栏组件，由**左侧消息工具区**和**右侧更新工具区**两部分组成，中间以分隔线分隔。仅 `like` / `unlike` 按钮会弹出反馈表单（`UserFeedback`），其余按钮直接触发 `onAction`。
 
@@ -371,6 +376,6 @@ enum MessageToolsStatus {
 
 ## 关联组件
 
-- [ToolBtn](../atomic/tool-btn.md) — 单项工具按钮
-- [UserFeedback](./user-feedback.md) — 点赞/踩反馈面板
-- [DeleteTool](./delete-tool.md) — 删除二次确认
+- [ToolBtn](/components/feedback/tool-btn) — 单项工具按钮
+- [UserFeedback](/components/feedback/user-feedback) — 点赞/踩反馈面板
+- [DeleteTool](/components/feedback/delete-tool) — 删除二次确认

package/dist/mcp/generated/docs/messages.md

@@ -107,6 +107,9 @@ enum MessageRole {
   // 信息消息
   Info = 'info',
 
+  // human-in-the-loop 中断消息
+  Interrupt = 'interrupt',
+
   // 加载中消息
   Loading = 'loading',
 
@@ -138,23 +141,32 @@ enum MessageRole {
 
 ```typescript
 enum MessageStatus {
-  // 等待中
-  Pending = 'pending',
-
-  // 流式输出中
-  Streaming = 'streaming',
-
   // 已完成
   Complete = 'complete',
 
+  // 已禁用
+  Disabled = 'disabled',
+
   // 错误
   Error = 'error',
 
+  // 请求中
+  Fetching = 'fetching',
+
+  // 等待中
+  Pending = 'pending',
+
   // 已停止
   Stop = 'stop',
 
-  // 已禁用
-  Disabled = 'disabled',
+  // 停止请求中
+  StopLoading = 'stop-loading',
+
+  // 流式输出中
+  Streaming = 'streaming',
+
+  // 成功
+  Success = 'success',
 }
 ```
 
@@ -337,6 +349,58 @@ const knowledgeRagMessage: ActivityMessage = {
 | `url`        | `string` | 文档预览链接     |
 | `originFile` | `string` | 文档原始文件链接 |
 
+### InterruptMessage
+
+human-in-the-loop 中断消息，对应 AG-UI `RUN_FINISHED` 事件的 `outcome` 对象结构。`content.outcome.type === 'interrupt'` 时，[InterruptMessageRender](../components/agent/interrupt-message) 从 `interrupts` 渲染审批卡片或把 `UserQuestion` 交给输入区；`type: 'success'` 表示 resume 后的成功结果，`UserQuestion` 会根据 `result` 回显回答内容。类型详见 [中断类型 Interrupt](./interrupt.md)。
+
+```typescript
+type RunFinishedOutcome = { interrupts: Interrupt[]; type: 'interrupt' } | { type: 'success' };
+
+type InterruptMessage = BaseMessage<
+  MessageRole.Interrupt,
+  {
+    message?: string;
+    outcome?: RunFinishedOutcome;
+    result?: BaseResume<InterruptReason>;
+    runId?: string;
+    threadId?: string;
+  }
+>;
+
+const interruptMessage: InterruptMessage = {
+  id: 'interrupt-message-1',
+  messageId: 'interrupt-message-1',
+  role: MessageRole.Interrupt,
+  status: MessageStatus.Pending,
+  content: {
+    message: '算法方案评审单需要您关注',
+    runId: 'run_ai_dev_tool_approval',
+    threadId: 'thread_ai_dev_tool_approval',
+    outcome: {
+      type: 'interrupt',
+      interrupts: [
+        {
+          id: 'interrupt_ai_dev_tool_approval',
+          reason: InterruptReason.AIDevToolApproval,
+          toolCallId: 'tool_call_review_ticket',
+          message: '算法方案评审单需要您关注',
+          metadata: {
+            ticket: {
+              approvers: ['张三', '李四'],
+              sn: 'REV-2026-04-24-001',
+              status: APPROVAL_STATUS.PENDING,
+              submit_time: '2026-04-24 14:30:15',
+              title: '算法方案评审单',
+              url: 'https://example.com/review-tickets/REV-2026-04-24-001',
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+```
+
 ### InfoMessage
 
 信息消息：
@@ -473,6 +537,6 @@ interface CustomMessage extends BaseMessage<'custom-role'> {
 
 ## 关联组件
 
-- [MessageContainer](../components/molecular/message-container.md) — 消息列表
-- [MessageRender](../components/molecular/message-render.md) — 单条消息渲染
-- [ChatContainer](../components/molecular/chat-container.md) — 聊天容器
+- [MessageContainer](../components/setup/message-container) — 消息列表
+- [MessageRender](../components/message/message-render) — 单条消息渲染
+- [ChatContainer](../components/setup/chat-container) — 聊天容器

package/dist/mcp/generated/docs/overflow-tips.md

@@ -203,7 +203,7 @@ type OverflowTipsValue = Partial<TippyProps> & {
 
 ## 关联组件
 
-- [DescPanel](../components/atomic/desc-panel.md) — 描述区溢出
-- [ExecutionSummary](../components/molecular/execution-summary.md) — 侧栏摘要标签
-- [ToolcallRender](../components/molecular/toolcall-render.md) — 工具调用标题
-- [ChatInput](../components/molecular/chat-input.md) — `@` 菜单项（内部 AiSlashMenu）
+- [DescPanel](../components/rendering/desc-panel) — 描述区溢出
+- [ExecutionSummary](../components/agent/execution-summary) — 侧栏摘要标签
+- [ToolcallRender](../components/agent/toolcall-render) — 工具调用标题
+- [ChatInput](../components/input/chat-input) — `@` 菜单项（内部 AiSlashMenu）

package/dist/mcp/generated/docs/preview-toolbar.md

@@ -0,0 +1,42 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+图片预览的缩放、旋转、下载等工具按钮。 源码位置：src/components/image-preview/preview-toolbar.vue。
+
+---
+<!-- FULL DOC -->
+
+# PreviewToolbar 图片预览工具栏
+
+> **能力域**：媒体文件
+
+## 源码事实
+
+- **源码位置**：`src/components/image-preview/preview-toolbar.vue`
+- **能力说明**：图片预览的缩放、旋转、下载等工具按钮。
+
+## API 摘要
+
+### Props
+
+- `{ activeIndex: number; currentImageInfo?: null | { resolution?: string; width?: number }; isMultiple: boolean; showInfo: boolean; total: number; }`
+
+### Emits
+
+- `{ (e: 'zoomIn'): void; (e: 'zoomOut'): void; (e: 'rotate'): void; (e: 'reset'): void; (e: 'download'): void; }`
+
+### Slots
+
+- `extra`
+
+### Expose
+
+- 无。
+
+## 组件依赖
+
+- 无组件依赖或仅依赖基础库。
+
+## 使用建议
+
+- 优先通过上层组合组件使用；直接使用前请确认 props 数据结构来自对应类型定义。

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

@@ -0,0 +1,88 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。 源码位置：src/components/ai-questions/questions-container.vue。
+
+### 关联组件
+- **user-question-card** — 用户问题中断交互请使用实际可渲染的问题卡片组件
+- **user-question-option** — 用户问题选项行由实际中断组件承载
+- **interrupt-message** — HITL 中断消息由 InterruptMessage 分发到具体问题组件
+
+---
+<!-- FULL DOC -->
+
+# QuestionsContainer 问题容器占位
+
+> **能力域**：辅助能力
+
+`QuestionsContainer` 当前只是保留在源码目录中的空文件，占位路径为 `src/components/ai-questions/questions-container.vue`。它没有模板、脚本、样式、props、emits、slots 或任何渲染行为。
+
+本文档保留该条目，是为了在组件总览和 MCP 文档检索中明确说明：它不是当前可用能力。
+
+## 源码事实
+
+- **源码位置**：`src/components/ai-questions/questions-container.vue`
+- **文件大小**：`0` 字节
+- **能力说明**：源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。
+
+## 当前状态
+
+| 项目     | 状态 |
+| -------- | ---- |
+| 模板     | 无   |
+| 脚本逻辑 | 无   |
+| 样式     | 无   |
+| Props    | 无   |
+| Emits    | 无   |
+| Slots    | 无   |
+| Expose   | 无   |
+
+## 不可用示例
+
+下面的写法不会产生任何可见 UI，也不会承载问题列表逻辑：
+
+```vue
+<template>
+  <!-- 不建议使用：当前组件为空文件 -->
+  <QuestionsContainer />
+</template>
+```
+
+## 推荐替代
+
+如果要展示用户问题中断或选项交互，请使用已经实现的中断消息组件链路：
+
+```vue
+<template>
+  <InterruptMessage :message="message" />
+</template>
+```
+
+或在具体场景中使用：
+
+- [InterruptMessage](../agent/interrupt-message.md) — 中断消息分发入口。
+- [UserQuestionCard](../agent/user-question-card.md) — 用户问题中断交互面板。
+- [UserQuestionOption](../agent/user-question-option.md) — 用户问题选项行。
+
+## API
+
+### Props
+
+- 无。
+
+### Emits
+
+- 无。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 使用建议
+
+- 不建议在业务中使用该组件。
+- 如果后续补齐实现，需要同步更新本文档的能力说明、示例、API 与关联组件。