@blueking/chat-x 0.0.48-beta.1 → 0.0.49-beta.2

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

@@ -1,54 +1,61 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-渲染助手消息主体、工具调用与文件内容，默认插槽可覆盖正文渲染。 源码位置：src/components/chat-message/assistant-message/assistant-message.vue。
+渲染助手 Markdown 正文、ToolCallRender 工具调用列表，以及 property.artifacts 文件卡片； 默认插槽仅覆盖正文。源码位置：src/components/chat-message/assistant-message/assistant-message.vue。
 
 ### 关联组件
 - **message-render** — 由 MessageRender 在 role 为 assistant 时创建
 - **tool-message** — 工具结果通过 toolCall.toolMessage 内联或独立 tool 消息关联展示
 - **toolcall-render** — 多条工具调用由 ToolcallRender 统一渲染
+- **file-artifact-panel** — property.artifacts 文件产物点击后在侧栏预览
 
 ---
 <!-- FULL DOC -->
 
 # AssistantMessage AI 助手消息
+
 ## 源码事实
 
 - **源码位置**：`src/components/chat-message/assistant-message/assistant-message.vue`
 - **能力域**：消息系统
-- **能力说明**：渲染助手消息主体、工具调用与文件内容，默认插槽可覆盖正文渲染。
+- **能力说明**：渲染助手 Markdown 正文、工具调用列表与 `property.artifacts` 文件产物。
 
-> **能力域**：消息系统
+> **导出说明**：`AssistantMessage` **未**从 `@blueking/chat-x` 包入口导出（入口同名是 TS interface）。消费方请用 `MessageRender` / `MessageContainer`。下文 `AssistantMessageComp` 为文档站内部相对路径示例。
 
-AI 助手消息展示组件，负责渲染 AI 回复的文本内容和工具调用（Tool Calls）结果。
+AI 助手消息展示组件：正文（Markdown）、工具调用（Tool Calls）、文件产物卡片。
 
 ## 渲染管线
 
 ```
 AssistantMessage（根类名：ai-assistant-message）
-├── ai-assistant-message-content（内容区）
-│   └── [default slot] 或 ContentRender → MarkdownContent（Markdown 渲染）
-└── ToolCallRender × N（每个 toolCall 独立渲染，不受 slot 影响）
+├── ai-assistant-message-content（内容区，v-if content）
+│   └── [default slot { content }] 或 ContentRender → MarkdownContent
+├── ToolCallRender × N（toolCalls，不受 slot 影响）
+└── MessageArtifacts（v-if property.artifacts 非空）
+      └── ArtifactFileCard × N（点击 → useArtifactPreview → 侧栏 FileArtifactPanel → ArtifactPreviewHost）
 ```
 
-- **内容区**：`content` 字符串传入 `ContentRender`，内部固定使用 `MessageContentType.Text` 类型，最终由 `MarkdownContent` 渲染 Markdown
-- **工具调用区**：`toolCalls` 数组中每一项渲染一个 `ToolCallRender`，位于内容区**下方**，与 slot 无关
+- **内容区**：`content` 经 `ContentRender`（`MessageContentType.Text`）由 `MarkdownContent` 渲染；default slot 仅收到 `{ content }`
+- **工具调用区**：每个 `toolCall` 渲染一个 `ToolCallRender`，位于内容区下方
+- **文件产物区**：读取 `property.artifacts`，用 `uid ?? String(id)` 作为 `messageUid` 传给 `MessageArtifacts`
 
 ## 基础用法
 
 ```vue
 <template>
-  <AssistantMessage
-    :content="content"
-    :status="status"
-  />
+  <MessageRender :message="message" />
 </template>
 
 <script setup lang="ts">
-  import { AssistantMessage, MessageStatus } from '@blueking/chat-x';
-
-  const content = '你好！我是 AI 助手，有什么可以帮助你的吗？';
-  const status = MessageStatus.Complete;
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Assistant,
+    content: '你好！我是 AI 助手，有什么可以帮助你的吗？',
+    status: MessageStatus.Complete,
+  };
 </script>
 ```
 
@@ -60,16 +67,18 @@ AssistantMessage（根类名：ai-assistant-message）
 
 ```vue
 <template>
-  <AssistantMessage
-    :content="markdownContent"
-    status="complete"
-  />
+  <MessageRender :message="message" />
 </template>
 
 <script setup lang="ts">
-  import { AssistantMessage } from '@blueking/chat-x';
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
 
-  const markdownContent = `## Vue 3 核心特性
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Assistant,
+    status: MessageStatus.Complete,
+    content: `## Vue 3 核心特性
 
 Vue 3 引入了多项重要更新：
 
@@ -84,7 +93,8 @@ const count = ref(0);
 const doubled = computed(() => count.value * 2);
 \\\`\\\`\\\`
 
-> 更多详情请参考 [Vue 3 官方文档](https://vuejs.org)。`;
+> 更多详情请参考 [Vue 3 官方文档](https://vuejs.org)。`,
+  };
 </script>
 ```
 
@@ -126,27 +136,30 @@ const doubled = computed(() => count.value * 2);
 
 ```vue
 <template>
-  <AssistantMessage
-    content="让我帮你查询一下天气信息。"
-    :status="MessageStatus.Complete"
-    :tool-calls="toolCalls"
-  />
+  <MessageRender :message="message" />
 </template>
 
 <script setup lang="ts">
-  import { AssistantMessage, MessageStatus } from '@blueking/chat-x';
-
-  const toolCalls = [
-    {
-      id: 'call_1',
-      type: 'function',
-      function: {
-        name: 'get_weather',
-        arguments: '{"city": "北京", "unit": "celsius"}',
-        description: '获取指定城市的天气信息',
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Assistant,
+    content: '让我帮你查询一下天气信息。',
+    status: MessageStatus.Complete,
+    toolCalls: [
+      {
+        id: 'call_1',
+        type: 'function',
+        function: {
+          name: 'get_weather',
+          arguments: '{"city": "北京", "unit": "celsius"}',
+          description: '获取指定城市的天气信息',
+        },
       },
-    },
-  ];
+    ],
+  };
 </script>
 ```
 
@@ -285,20 +298,17 @@ AI 可在一次回复中发起多个工具调用，组件依次渲染：
 
 ```vue
 <template>
-  <AssistantMessage
-    :content="content"
-    :tool-calls="toolCalls"
-  >
+  <MessageRender :message="message">
     <template #default="{ content }">
       <div style="padding: 12px; background: #f0f9ff; border-left: 3px solid #3a84ff; border-radius: 4px;">
-        🤖 {{ content }}
+        {{ content }}
       </div>
     </template>
-  </AssistantMessage>
+  </MessageRender>
 </template>
 ```
 
-> **注意**：使用默认插槽后，内置的 `MarkdownContent`（Markdown 渲染）被替换，需要自行处理内容格式化。
+> **注意**：使用默认插槽后，内置 Markdown 渲染被替换，需自行处理格式化。slot 运行时仅保证 `{ content }`（见 [MessageRender](/components/message/message-render)）。
 
 **渲染效果**
 
@@ -358,28 +368,80 @@ AI 可在一次回复中发起多个工具调用，组件依次渲染：
 </script>
 ```
 
+## 文件产物
+
+当 `property.artifacts` 非空时，在工具调用区下方渲染 `MessageArtifacts` 文件卡片列表。点击卡片会通过 `useArtifactPreview` 打开 `ChatContainer` 侧栏「文件产物」Tab（见 [FileArtifactPanel](/components/message/file-artifact-panel)）。
+
+`AIFileInfo` 仅含元信息（`name` / `outputId` / `size` / `type`）；`download_url` / `preview_url` 由容器 `onArtifactClick` 异步获取。命中唯一文件依赖 `messageUid = uid ?? String(id)` + 卡片下标 + `outputId`。
+
+侧栏预览由面板内 `ArtifactPreviewHost` 按类型分派（详见面板文档「预览机制」）：
+
+| type | 预览依赖 | 渲染 |
+| ---- | -------- | ---- |
+| `html` / `markdown` / `md` / `txt` / `json` | `download_url` | 正文直渲染（srcdoc / MarkdownContent / `<pre>`） |
+| `pdf` / `jpg` 等 | `preview_url` | iframe（一般为后台转好的 PDF） |
+
+`md` 与 `markdown` 等价（见 `AIFileType.Md` / `AIFileType.Markdown`）。预览重载、`force` 重试与取链约定见 [FileArtifactPanel 预览机制](/components/message/file-artifact-panel#预览机制)。
+
+```vue
+<template>
+  <MessageRender :message="message" />
+</template>
+
+<script setup lang="ts">
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+  import type { AIFileInfo } from '@blueking/chat-x';
+
+  const artifacts: AIFileInfo[] = [
+    { name: '监控大盘周报.html', outputId: 'output-html', size: 10240, type: 'html' },
+    { name: '系统配置说明.md', outputId: 'output-md', size: 8192, type: 'md' },
+    { name: '周例会纪要.txt', outputId: 'output-txt', size: 4096, type: 'txt' },
+    { name: '告警策略配置.json', outputId: 'output-json', size: 2048, type: 'json' },
+    { name: '立项说明书.pdf', outputId: 'output-pdf', size: 204800, type: 'pdf' },
+    { name: '巡检现场照片.jpg', outputId: 'output-jpg', size: 1048576, type: 'jpg' },
+  ];
+
+  const message = {
+    id: 'a1',
+    messageId: 'a1',
+    uid: 'assistant-uid-1',
+    role: MessageRole.Assistant,
+    status: MessageStatus.Complete,
+    content: '已为你生成一组评审材料，可点击卡片在侧栏预览或下载：',
+    property: { artifacts },
+  };
+</script>
+```
+
+**渲染效果（文档站内部示例；无 Provider 时卡片不可点击预览）**
+
 ## API
 
 ### Props
 
 组件 Props 来自 `Partial<AssistantMessage>`（所有字段均可选）：
 
-| 属性名    | 类型                    | 说明                                                           |
-| --------- | ----------------------- | -------------------------------------------------------------- |
-| content   | `string`                | AI 回复的文本内容，支持 Markdown，`undefined` 时渲染为空字符串 |
-| status    | `MessageStatus`         | 消息状态，影响 Markdown 渲染模式和 ToolCallRender 的状态标题   |
-| toolCalls | `ToolCall[]`            | 工具调用列表，每项渲染一个 `ToolCallRender`                    |
-| id        | `number \| string`      | 消息 ID                                                        |
-| messageId | `number \| string`      | 消息唯一标识                                                   |
-| name      | `string`                | 消息发送者名称（可选）                                         |
-| role      | `MessageRole.Assistant` | 消息角色，固定为 `'assistant'`                                 |
-| property  | `object`                | 消息附加属性，本组件不使用，由父组件（`MessageContainer`）消费 |
+| 属性名    | 类型                    | 说明                                                                                      |
+| --------- | ----------------------- | ----------------------------------------------------------------------------------------- |
+| content   | `string`                | AI 回复文本，支持 Markdown；空值时不渲染内容区                                            |
+| status    | `MessageStatus`         | 影响 ContentRender / ToolCallRender 状态表现                                              |
+| toolCalls | `ToolCall[]`            | 工具调用列表，每项渲染一个 `ToolCallRender`                                               |
+| id        | `number \| string`      | 消息 ID；无 `uid` 时回退为 `messageUid`                                                   |
+| messageId | `number \| string`      | 消息唯一标识                                                                              |
+| uid       | `string`                | 优先作为文件产物命中 / 「在对话中定位」的 `messageUid`                                    |
+| name      | `string`                | 消息发送者名称（可选）                                                                    |
+| role      | `MessageRole.Assistant` | 消息角色，固定为 `'assistant'`                                                            |
+| property  | `{ artifacts?: AIFileInfo[]; extra?: ... }` | **本组件消费** `property.artifacts` 渲染文件卡片；`extra` 等由上层按需使用 |
 
 ### Slots
 
-| 插槽名  | 参数                  | 说明                                                 |
-| ------- | --------------------- | ---------------------------------------------------- |
-| default | `{ content: string }` | 替换内容区渲染，toolCalls 在内容区外独立渲染不受影响 |
+| 插槽名  | 参数                  | 说明                                                              |
+| ------- | --------------------- | ----------------------------------------------------------------- |
+| default | `{ content: string }` | 替换内容区渲染；toolCalls / MessageArtifacts 在内容区外独立渲染 |
+
+### Events / Expose
+
+无。
 
 ## 类型定义
 
@@ -426,4 +488,5 @@ interface ToolMessage extends BaseMessage<MessageRole.Tool, string> {
 
 - [MessageRender](/components/message/message-render) — assistant 角色由其实例化
 - [ToolMessage](/components/message/tool-message) — 工具执行结果可通过 toolCall.toolMessage 内联
-- [ToolcallRender](/components/agent/toolcall-render) — 工具调用列表渲染
+- [ToolcallRender](/components/agent/toolcall-render) — 工具调用列表渲染
+- [FileArtifactPanel](/components/message/file-artifact-panel) — 文件产物侧栏列表与分类型预览 Host

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

@@ -133,9 +133,9 @@ ai-chat-container（:data-ai-size="size"）
 
 侧边栏默认包含「执行情况」Tab，展示所有工具调用和 FlowAgent 类型的 Activity 消息。支持关键词搜索过滤和点击定位到对话中的消息位置。
 
-**展示条件**：当 `executionGroups` 为空且 `keyword` 为空时，不渲染侧栏 Tab 与 `ExecutionSummary`（折叠按钮亦隐藏）；主区域仍可正常展示 `messages` 中的对话内容。用户在执行情况中输入搜索词后，侧栏会保持展示以显示「搜索结果为空」等状态。`renderMode === Share` 分享态同样按上述执行数据条件展示侧栏（开放只读查看流程智能体详情/证据/执行情况），不再强制隐藏折叠；仅底部输入区保持隐藏。
+**展示条件**：当 `executionGroups` 为空且 `keyword` 为空时，不渲染侧栏 Tab 与 `ExecutionSummary`（折叠按钮亦隐藏）；主区域仍可正常展示 `messages` 中的对话内容。用户在执行情况中输入搜索词后，侧栏会保持展示以显示「搜索结果为空」等状态。`renderMode === Share` 分享态同样按上述执行数据条件展示侧栏（开放只读查看流程智能体详情/证据/执行情况），不再强制隐藏折叠；仅底部输入区保持隐藏。**例外**：当[「文件产物」Tab](#内置-文件产物-tab)存在时，侧栏不再受「`executionGroups` 为空」约束，可独立展示文件预览。
 
-**自定义 Tab 联动**：当 `executionGroups` 变为空且搜索词已清空时，容器会**自动重置自定义 Tab**（`resetCustomTab`），避免残留节点详情等 Tab；若用户仍在搜索（`keyword` 非空），不会触发重置。
+**自定义 Tab 联动**：当 `executionGroups` 变为空且搜索词已清空时，容器会**自动重置自定义 Tab**（`resetCustomTab`），避免残留节点详情等 Tab；若用户仍在搜索（`keyword` 非空）或存在「文件产物」Tab，不会触发重置。
 
 ```vue
 <template>
@@ -239,6 +239,84 @@ ai-chat-container（:data-ai-size="size"）
 </script>
 ```
 
+### 内置「文件产物」Tab
+
+除「执行情况」外，容器内置一个按需出现的固定 Tab —— **「文件产物」**（`name: 'file-artifact'`），用于聚合预览当前会话所有 `AssistantMessage.property.artifacts`（按 `outputId` 去重）：
+
+- **静默挂载**：会话已有文件产物时，容器通过 `ensureCustomTab` 挂上该 Tab，**不展开侧栏、不切换当前选中**（避免从「执行情况」展开时被抢走焦点），并保证命中态有效（默认第一个 `outputId`）
+- **主动打开**：点击 AI 回复中的文件卡片（[ArtifactFileCard](/components/message/assistant-message)）时，容器通过 `useArtifactPreviewProvider` 以 `outputId` 命中该文件，再 `addCustomTab` 展开侧栏并选中「文件产物」
+- **排序 / 关闭**：`order: -1` 排在「执行情况」之前，`closable: false` 不可关闭
+- **显隐解耦**：该 Tab 存在时，侧栏展示不再受「`executionGroups` 为空」约束（即使当前会话没有执行类消息，也能独立展示文件产物侧栏）；会话切换或无文件产物时自动移除并重置命中态
+- **内容**：由 [FileArtifactPanel](/components/message/file-artifact-panel) 渲染列表与下载头，预览委托内部 `ArtifactPreviewHost`；`download_url` / `preview_url` 通过 `onArtifactClick` 异步获取。文本类（`html` / `markdown` / `md` / `txt` / `json`）拉 `download_url` 正文直渲染（`md` 与 `markdown` 等价）；其余类型用 `preview_url` iframe（一般为后台转好的 PDF）。预览重载键为 `outputId:type`；失败重试会 `force` 绕过 URL 缓存
+- **状态管理**：命中、切换与 URL 缓存由 [useArtifactPreview](/composables/use-artifact-preview) 提供（Provider 在容器内、Consumer 在文件卡片 / 面板内）；正文加载与分类型渲染由 Host 内部完成；常规取链只传 `file`，勿传 `undefined` 作为第二参
+- **未传 `onArtifactClick`**：下载按钮隐藏，预览区展示无数据
+
+详见 [FileArtifactPanel 文件产物预览](/components/message/file-artifact-panel) 与 [useArtifactPreview 文件产物预览](/composables/use-artifact-preview)。
+
+#### 接入示例
+
+```vue
+<template>
+  <ChatContainer
+    v-model="input"
+    :messages="messages"
+    :on-artifact-click="onArtifactClick"
+    @send-message="handleSend"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref, shallowRef } from 'vue'
+  import {
+    ChatContainer,
+    MessageRole,
+    MessageStatus,
+    type AIFileInfo,
+    type Message,
+  } from '@blueking/chat-x'
+
+  const input = ref('')
+  const messages = shallowRef<Message[]>([
+    {
+      id: 'u1',
+      messageId: 'u1',
+      role: MessageRole.User,
+      status: MessageStatus.Complete,
+      content: '整理本周评审材料',
+    },
+    {
+      id: 'a1',
+      messageId: 'a1',
+      uid: 'assistant-uid-1',
+      role: MessageRole.Assistant,
+      status: MessageStatus.Complete,
+      content: '已生成评审材料，点击卡片可在侧栏预览：',
+      property: {
+        artifacts: [
+          { name: '周报.html', outputId: 'a-html', size: 10240, type: 'html' },
+          { name: '说明.md', outputId: 'a-md', size: 8192, type: 'md' },
+          { name: '配置.json', outputId: 'a-json', size: 2048, type: 'json' },
+          { name: '立项.pdf', outputId: 'a-pdf', size: 204800, type: 'pdf' },
+        ] satisfies AIFileInfo[],
+      },
+    },
+  ])
+
+  /** 文本类预览依赖 download_url；iframe 类依赖 preview_url */
+  const onArtifactClick = async (file: AIFileInfo) => {
+    const res = await api.getArtifactUrls(file.outputId)
+    return {
+      download_url: res.download_url,
+      preview_url: res.preview_url,
+    }
+  }
+
+  const handleSend = () => {
+    /* ... */
+  }
+</script>
+```
+
 ### 自定义 Tab 与「在对话中定位」
 
 `addCustomTab` 的 `data` 可携带 **`messageUid`**（与对应活动消息的 `message.uid` 一致）。`ChatContainer` 在侧栏用 `<component :is="sideRenderComponent">`（内部计算属性，见上文「侧栏渲染扩展」）渲染自定义 Tab 时，会向子组件提供 **`locateButton` 插槽**：默认渲染「在对话中定位」按钮，点击后调用内部 `handleLocateMessageGroup(messageUid)`，优先滚动到主区域 `document.getElementById(messageUid)`；若不存在该节点，则在当前 `messageGroups` 中查找包含 `message.uid === messageUid` 的消息组，并滚动到该组的容器（`MessageGroup.uid` 作为组级 `id`）。
@@ -376,9 +454,9 @@ ai-chat-container（:data-ai-size="size"）
 
 ## 用户问题中断
 
-当会话中最近一条待处理 interrupt 包含 `InterruptReason.UserQuestion` 时，`ChatContainer` 会在 `ChatInput` 上方显示 [UserQuestionCard](/components/agent/user-question-card)。
+当会话中最近一条待处理 interrupt 包含 `InterruptReason.UserQuestion` 时，`ChatContainer` 会在 `ChatInput` 上方显示 [UserQuestionCard](/components/agent/user-question-card)（一次一题，标题栏可切换题目）。
 
-- **结构化作答**：用户在卡片内完成选择或点击「跳过」后，通过 `onInterruptResume(payload, interrupt)` 回传 `UserQuestionResume`。
+- **结构化作答**：用户在卡片内逐题选择（单选可自动跳下一题），点击「完成」或「跳过」后通过 `onInterruptResume(payload, interrupt)` 回传 `UserQuestionResume`。
 - **输入框发送**：用户也可在输入框直接点击发送；容器会调用 `onSendMessage(content, docSchema, options)`，其中 `options.interrupt` 为当前激活的 UserQuestion，`options.payload` 为 `buildSkipResumePayload` 生成的 skip resume（`status: 'cancelled'`，`answers: []`）。此时**不会自动清空**输入框，由业务侧在 `onSendMessage` 内决定如何处理 `content` 与中断恢复。
 
 ```vue
@@ -618,20 +696,21 @@ ai-chat-container（:data-ai-size="size"）
 
 ChatContainer 的 Props 继承自 `ChatInputProps` 和 `MessageContainerProps`（排除 `enableSelection` 和 `messageGroups`），另外新增：
 
-| 属性名                    | 类型                                                                                  | 默认值    | 说明                                                                                                                                 |
-| ------------------------- | ------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| chatLoading               | `boolean`                                                                             | —         | 整体加载状态，`true` 时显示 Loading 遮罩                                                                                             |
-| commonTippyOptions        | `AITippyProps`                                                                        | —         | 通用 Tippy 配置，注入到所有使用 `v-overflow-tips` 的子组件                                                                           |
-| executionTabVisible       | `boolean`                                                                             | `true`    | 「执行情况」Tab 是否展示；为 `false` 时从 Tab 栏隐藏，若正被选中则切到首个可见 Tab                                                   |
-| getSideRenderComponent    | `(h, props?) => VNode \| undefined`                                                   | —         | 自定义侧栏内容区渲染；未返回时使用 `selectedTab.data.component`                                                                      |
-| getSideTabRenderComponent | `(h, tab, { removeCustomTab }) => VNode \| undefined`                                 | —         | 自定义侧栏 Tab 标签渲染；未返回时使用默认图标 + 文案 + 关闭按钮                                                                      |
-| models                    | `IModelOption[]`                                                                      | —         | 可选模型列表（继承自 ChatInput）；传入后在发送按钮左侧展示 ModelSelector                                                             |
-| 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` 始终取自本组件               |
-| size                      | `'normal' \| 'small'`                                                                 | `'small'` | 字号主题：`small` 12px / `normal` 14px；根节点设置 `data-ai-size` 并注入 `useGlobalConfig`                                           |
-| welcomeTitle              | `string`                                                                              | —         | 欢迎页标题；未传时默认展示「你好，我是小鲸」                                                                                         |
-| onCustomTabChange         | `(tab: CustomTab) => Promise<any>`                                                    | —         | 自定义 Tab 切换回调，返回值作为 Tab 组件 props                                                                                       |
+| 属性名                    | 类型                                                                                     | 默认值    | 说明                                                                                                                                 |
+| ------------------------- | ---------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| chatLoading               | `boolean`                                                                                | —         | 整体加载状态，`true` 时显示 Loading 遮罩                                                                                             |
+| commonTippyOptions        | `AITippyProps`                                                                           | —         | 通用 Tippy 配置，注入到所有使用 `v-overflow-tips` 的子组件                                                                           |
+| executionTabVisible       | `boolean`                                                                                | `true`    | 「执行情况」Tab 是否展示；为 `false` 时从 Tab 栏隐藏，若正被选中则切到首个可见 Tab                                                   |
+| getSideRenderComponent    | `(h, props?) => VNode \| undefined`                                                      | —         | 自定义侧栏内容区渲染；未返回时使用 `selectedTab.data.component`                                                                      |
+| getSideTabRenderComponent | `(h, tab, { removeCustomTab }) => VNode \| undefined`                                    | —         | 自定义侧栏 Tab 标签渲染；未返回时使用默认图标 + 文案 + 关闭按钮                                                                      |
+| models                    | `IModelOption[]`                                                                         | —         | 可选模型列表（继承自 ChatInput）；传入后在发送按钮左侧展示 ModelSelector                                                             |
+| 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` 始终取自本组件。**数字型** `initialDivide` 还会作为内部侧栏宽度初值（驱动 `--resize-main-width`，并在展开时作为 `collapseChange` 的 `width`）；百分比等字符串则回退为 `400` |
+| size                      | `'normal' \| 'small'`                                                                    | `'small'` | 字号主题：`small` 12px / `normal` 14px；根节点设置 `data-ai-size` 并注入 `useGlobalConfig`                                           |
+| welcomeTitle              | `string`                                                                                 | —         | 欢迎页标题；未传时默认展示「你好，我是小鲸」                                                                                         |
+| onCustomTabChange         | `(tab: CustomTab) => Promise<any>`                                                       | —         | 自定义 Tab 切换回调，返回值作为 Tab 组件 props                                                                                       |
+| onArtifactClick           | `(file: AIFileInfo) => Promise<{ download_url?: string; preview_url?: string }>`          | —         | 异步获取下载 / 预览链接（按 `outputId` 缓存）。文本类预览依赖 `download_url`，iframe 类依赖 `preview_url`；未传则隐藏下载、预览无数据 |
 
 > 其余 Props（如 `messages`、`messageStatus`、`onSendMessage`、`shortcuts` 等）继承自 [ChatInput](/components/input/chat-input) 与 [MessageContainer](/components/setup/message-container)。
 

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

@@ -654,19 +654,11 @@ const handleSendMessage = async (
 
 ## 类型定义
 
+> `MessageStatus` 完整取值见 [常量枚举](../../types/constants)。与输入区相关：`pending` / `streaming` / `fetching` → 停止按钮；`complete` / `completed` / `error` / `stop` → 发送；`disabled` → 置灰。
+
 ```typescript
 import type { UserMessage } from '@blueking/chat-x';
 
-// 消息状态
-enum MessageStatus {
-  Pending = 'pending', // 等待中（显示停止按钮）
-  Streaming = 'streaming', // 流式输出中（显示停止按钮）
-  Complete = 'complete', // 完成（显示发送按钮）
-  Error = 'error', // 错误（显示发送按钮）
-  Stop = 'stop', // 已停止（显示发送按钮）
-  Disabled = 'disabled', // 禁用（发送按钮置灰）
-}
-
 // 上传状态
 enum UploadStatus {
   Pending = 'pending', // 上传中

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-汇总 MessageRole、MessageStatus（含 Fetching 请求中）、MessageContentType、MessageToolsStatus、MessageState、Z-Index 与 CONST_MESSAGE_TOOLS 等导出常量。 用于构造消息、配置 MessageContainer 工具栏与输入态，以及层级与默认快捷指令。与类型 messages 配套使用。
+汇总 MessageRole、MessageStatus（含 Fetching 请求中、Complete/Completed 完成态兼容）、MessageContentType、MessageToolsStatus、MessageState、Z-Index 与 CONST_MESSAGE_TOOLS 等导出常量。 用于构造消息、配置 MessageContainer 工具栏与输入态，以及层级与默认快捷指令。与类型 messages 配套使用。
 
 ### 关联组件
 - **message-tools** — 默认工具 ID 与展示
@@ -58,6 +58,7 @@ enum MessageRole {
 ```typescript
 enum MessageStatus {
   Complete = 'complete',
+  Completed = 'completed', // 与 Complete 同为完成态，兼容后端/协议返回的 completed
   Disabled = 'disabled',
   Error = 'error',
   Fetching = 'fetching', // 请求中（例如已发用户消息、尚未开始流式，与末尾 Loading 占位一致）
@@ -71,6 +72,7 @@ enum MessageStatus {
 
 | 枚举值          | 说明 |
 | --------------- | ---- |
+| `Complete` / `Completed` | 已完成。`complete` 为库内常用值；`completed` 与之语义相同，用于兼容外部协议或后端返回。`ToolcallRender` 等将二者与 `success` 一并视为成功态。 |
 | `Fetching`      | 请求中：与 `useMessageGroup` 在末尾用户消息后注入的 Loading 占位（`LOADING_MESSAGE_ID`）配合时，`ChatContainer` 会将传入输入区与列表底部的状态推导为该值，便于展示「停止」与禁止重复发送。 |
 
 ### InterruptReason

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

@@ -216,18 +216,10 @@ enum MessageContentType {
   KnowledgeRag = 'knowledge_rag',
   Other = 'other',
 }
-
-// 消息状态
-enum MessageStatus {
-  Pending = 'pending',
-  Streaming = 'streaming',
-  Complete = 'complete',
-  Error = 'error',
-  Stop = 'stop',
-  Disabled = 'disabled',
-}
 ```
 
+> `MessageStatus` 完整取值见 [常量枚举](../../types/constants)；本组件主要关心 `error`（错误内容）与流式相关状态。
+
 ## 使用场景
 
 - **AI 文本回复渲染**：`AssistantMessage` 内部用 `ContentRender` 渲染 AI 回复内容，`status` 配合流式响应