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

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

@@ -1,26 +1,29 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-渲染用户消息，支持文本、键值、Markdown、引用、文件和编辑态输入。 源码位置：src/components/chat-message/user-message/user-message.vue。
+渲染用户消息：纯文本（非 Markdown）、键值引用、二进制附件与编辑态 ChatInput / ShortcutRender； 工具栏含 copy / cite / edit / delete。源码位置：src/components/chat-message/user-message/user-message.vue。
 
 ### 关联组件
 - **message-render** — 由 MessageRender 在 role 为 user 时创建
 - **message-tools** — 消息工具栏交互与状态由 MessageTools 体系承载
+- **message-time** — createdAt 经工具栏 prepend 插槽展示
 - **message-container** — 嵌入列表时由 MessageContainer 管理分组与多选
+- **chat-input** — 编辑态普通消息使用 ChatInput
 
 ---
 <!-- FULL DOC -->
 
 # UserMessage 用户消息
+
 ## 源码事实
 
 - **源码位置**：`src/components/chat-message/user-message/user-message.vue`
 - **能力域**：消息系统
-- **能力说明**：渲染用户消息，支持文本、键值、Markdown、引用、文件和编辑态输入。
+- **能力说明**：渲染用户消息：纯文本、键值引用、文件附件与编辑态输入（**不**渲染 Markdown）。
 
-> **能力域**：消息系统
+> **导出说明**：`UserMessage` **未**从 `@blueking/chat-x` 包入口导出（入口同名是 TS interface）。消费方请用 `MessageRender` / `MessageContainer`。下文 `UserMessageComp` 为文档站内部相对路径示例。
 
-用户消息展示组件，右对齐显示用户发送的消息内容。支持纯文本、多媒体（图片/文件）、文本引用、结构化引用、快捷指令等多种内容形式，以及消息的内联编辑功能。
+用户消息展示组件，右对齐。支持纯文本、多媒体（图片/文件）、文本引用、结构化引用、快捷指令，以及内联编辑。
 
 ## 组件结构
 
@@ -44,9 +47,12 @@
 └── MessageTools（.ai-user-message-tools）
       v-if: messageToolsStatus !== 'hidden'
       visibility: hidden（默认）→ visible（:hover 时）
-      tools: [copy, cite, edit]，updateTools: []
+      tools: [copy, cite, edit, delete]，updateTools: []
+      #prepend slot → MessageTime（createdAt，工具图标左侧）
 ```
 
+> **时间随工具栏显隐**：时间位于工具栏内，与工具按钮共用 `visibility` 控制，因此同样在悬停消息时才可见。
+
 **编辑模式**（点击 `edit` 按钮后 `isEdit=true`）
 
 ```
@@ -67,28 +73,35 @@
 
 ## 基础用法
 
-`content` 为字符串时，通过 `TextContent` 渲染（内部使用 `MarkdownContent`，支持 Markdown 语法）。
+`content` 为字符串时，通过 `TextContent` 以**纯文本**插值渲染（`{{ content }}`），**不**走 Markdown。
 
 ```vue
 <template>
-  <UserMessage
-    :content="content"
+  <MessageRender
+    :message="message"
     :on-action="handleAction"
   />
 </template>
 
 <script setup lang="ts">
-  import { UserMessage, type IToolBtn } from '@blueking/chat-x';
-
-  const content = '你好，请帮我分析以下这段 Python 代码的性能瓶颈。';
+  import { MessageRender, MessageRole, MessageStatus, type IToolBtn } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.User,
+    content: '你好，请帮我分析以下这段 Python 代码的性能瓶颈。',
+    status: MessageStatus.Complete,
+  };
 
   const handleAction = async (tool: IToolBtn) => {
+    // copy / edit 有内置行为；cite / delete 需业务侧处理
     console.log('工具操作:', tool.id);
   };
 </script>
 ```
 
-> **工具栏**：鼠标悬停时，消息下方出现「复制」「引用」「编辑」三个操作按钮（CSS `visibility` 切换，始终占位）。
+> **工具栏**：悬停时显示「复制」「引用」「编辑」「删除」（CSS `visibility`，始终占位）。
 
 ## 多媒体消息
 
@@ -101,20 +114,26 @@
 
 ```vue
 <script setup lang="ts">
-  import { UserMessage, MessageContentType } from '@blueking/chat-x';
-
-  const content = [
-    {
-      type: MessageContentType.Binary, // 'binary'
-      url: 'https://example.com/screenshot.png',
-      mimeType: 'image/png',
-      filename: 'screenshot.png',
-    },
-    {
-      type: MessageContentType.Text, // 'text'
-      text: '请帮我分析这张架构图，指出其中的问题。',
-    },
-  ];
+  import { MessageRender, MessageContentType, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.User,
+    status: MessageStatus.Complete,
+    content: [
+      {
+        type: MessageContentType.Binary,
+        url: 'https://example.com/screenshot.png',
+        mimeType: 'image/png',
+        filename: 'screenshot.png',
+      },
+      {
+        type: MessageContentType.Text,
+        text: '请帮我分析这张架构图，指出其中的问题。',
+      },
+    ],
+  };
 </script>
 ```
 
@@ -133,12 +152,14 @@
 
 ```vue
 <script setup lang="ts">
-  import { UserMessage } from '@blueking/chat-x';
-
-  const content = '这段代码每次循环都发起请求，应该如何优化？';
-  const property = {
-    extra: {
-      cite: '// 原始代码\nfor (let i = 0; i < arr.length; i++) {\n  fetch(`/api/${arr[i]}`)\n}',
+  // 消费方将 property 挂在 message 上，经 MessageRender 透传
+  const message = {
+    role: 'user',
+    content: '这段代码每次循环都发起请求，应该如何优化？',
+    property: {
+      extra: {
+        cite: '// 原始代码\nfor (let i = 0; i < arr.length; i++) {\n  fetch(`/api/${arr[i]}`)\n}',
+      },
     },
   };
 </script>
@@ -150,18 +171,20 @@
 
 ```vue
 <script setup lang="ts">
-  import { UserMessage } from '@blueking/chat-x';
-
-  const content = '请帮我分析这份报表的数据趋势。';
-  const property = {
-    extra: {
-      cite: {
-        title: '销售数据分析',
-        data: [
-          { key: '报表名称', value: '2024 年 Q4 销售报表' },
-          { key: '时间范围', value: '2024年10月 - 12月' },
-          { key: '数据量', value: '12,580 条' },
-        ],
+  const message = {
+    role: 'user',
+    content: '请帮我分析这份报表的数据趋势。',
+    property: {
+      extra: {
+        cite: {
+          title: '销售数据分析',
+          type: 'structured',
+          data: [
+            { key: '报表名称', value: '2024 年 Q4 销售报表' },
+            { key: '时间范围', value: '2024年10月 - 12月' },
+            { key: '数据量', value: '12,580 条' },
+          ],
+        },
       },
     },
   };
@@ -182,34 +205,35 @@
 
 ```vue
 <script setup lang="ts">
-  import { UserMessage } from '@blueking/chat-x';
-
-  const content = '请帮我翻译这段文字';
-  const property = {
-    extra: {
-      shortcut: {
-        id: 'translate',
-        name: '翻译',
-        components: [
-          {
-            type: 'select',
-            key: 'targetLang',
-            name: '目标语言',
-            default: 'en',
-            options: [
-              { label: '英文', value: 'en' },
-              { label: '中文', value: 'zh' },
-            ],
-          },
-          {
-            type: 'textarea',
-            key: 'content',
-            name: '翻译内容',
-            fillBack: true,
-            default: '请帮我翻译这段文字',
-          },
-        ],
-        formModel: { targetLang: 'en', content: '请帮我翻译这段文字' },
+  const message = {
+    role: 'user',
+    content: '请帮我翻译这段文字',
+    property: {
+      extra: {
+        shortcut: {
+          id: 'translate',
+          name: '翻译',
+          components: [
+            {
+              type: 'select',
+              key: 'targetLang',
+              name: '目标语言',
+              default: 'en',
+              options: [
+                { label: '英文', value: 'en' },
+                { label: '中文', value: 'zh' },
+              ],
+            },
+            {
+              type: 'textarea',
+              key: 'content',
+              name: '翻译内容',
+              fillBack: true,
+              default: '请帮我翻译这段文字',
+            },
+          ],
+          formModel: { targetLang: 'en', content: '请帮我翻译这段文字' },
+        },
       },
     },
   };
@@ -236,8 +260,8 @@ binaryFiles 有值 → 进入编辑模式（editContent 可为空）
 
 ```vue
 <template>
-  <UserMessage
-    :content="content"
+  <MessageRender
+    :message="message"
     :on-action="handleAction"
     :on-input-confirm="handleInputConfirm"
     :on-shortcut-confirm="handleShortcutConfirm"
@@ -245,25 +269,35 @@ binaryFiles 有值 → 进入编辑模式（editContent 可为空）
 </template>
 
 <script setup lang="ts">
-  import { UserMessage, type IToolBtn, type TagSchema } from '@blueking/chat-x';
-
-  const content = '请帮我优化这段代码';
+  import {
+    MessageRender,
+    MessageRole,
+    MessageStatus,
+    type IToolBtn,
+    type TagSchema,
+    type UserMessage,
+  } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.User,
+    content: '请帮我优化这段代码',
+    status: MessageStatus.Complete,
+  };
 
   const handleAction = async (tool: IToolBtn) => {
-    // tool.id === 'edit'  → 组件内部自动切换编辑模式
-    // tool.id === 'copy'  → 自动复制（字符串直接复制，数组 JSON.stringify 后复制）
-    // tool.id === 'cite'  → 由外部 onAction 处理（组件内无内置行为）
+    // edit → 组件内切编辑态；copy → 组件内复制
+    // cite / delete → 无内置行为，业务侧处理（如删除会话消息）
     console.log('工具:', tool.id);
   };
 
-  const handleInputConfirm = async (content: string | InputContent[], docSchema: TagSchema) => {
-    console.log('编辑后内容:', content);
-    // 重新发送消息
+  const handleInputConfirm = async (content: UserMessage['content'], docSchema: TagSchema) => {
+    console.log('编辑后内容:', content, docSchema);
   };
 
   const handleShortcutConfirm = async (formModel: Record<string, unknown>) => {
     console.log('快捷指令表单:', formModel);
-    // 重新发送快捷指令
   };
 </script>
 ```
@@ -274,50 +308,86 @@ binaryFiles 有值 → 进入编辑模式（editContent 可为空）
 
 **内置工具列表（`CONST_USER_MESSAGE_TOOLS`）**
 
-| 工具 ID | 名称 | 内置行为                                     |
-| ------- | ---- | -------------------------------------------- |
-| `copy`  | 复制 | 字符串直接复制；数组 `JSON.stringify` 后复制 |
-| `cite`  | 引用 | 无内置行为，需通过 `onAction` 外部处理       |
-| `edit`  | 编辑 | 切换 `isEdit=true`，进入编辑模式             |
+| 工具 ID  | 名称 | 内置行为                                     |
+| -------- | ---- | -------------------------------------------- |
+| `copy`   | 复制 | 字符串直接复制；数组 `JSON.stringify` 后复制 |
+| `cite`   | 引用 | 无内置行为，需通过 `onAction` 外部处理       |
+| `edit`   | 编辑 | 切换 `isEdit=true`，进入编辑模式             |
+| `delete` | 删除 | 无内置行为，需通过 `onAction` 外部处理       |
 
 ```vue
-<!-- 隐藏工具按钮（从 DOM 移除，不占位） -->
-<UserMessage :content="content" message-tools-status="hidden" />
+<!-- 经 MessageRender 控制工具栏状态 -->
+<MessageRender
+  :message="message"
+  message-tools-status="hidden"
+/>
+<MessageRender
+  :message="message"
+  message-tools-status="disabled"
+/>
+```
+
+## supportUpload 透传
 
-<!-- 禁用工具按钮（保留占位，不可点击，无 hover 效果） -->
-<UserMessage :content="content" message-tools-status="disabled" />
+编辑态 `ChatInput` 的上传能力来自 `injectGlobalConfig().supportUpload`（通常由 `ChatContainer` 的 `supportUpload` prop 注册）。自定义 `#message` 插槽时须把同一配置链路保留，否则编辑态会与主输入区不一致。
+
+```vue
+<template>
+  <ChatContainer
+    :messages="messages"
+    :support-upload="true"
+    :on-agent-action="handleAgentAction"
+    :on-user-action="handleUserAction"
+  >
+    <template #message="{ message, messageToolsStatus, onInterruptResume }">
+      <MessageRender
+        :message="message"
+        :message-tools-status="messageToolsStatus"
+        :on-action="handleUserAction"
+        :on-input-confirm="(content, docSchema) => handleUserInputConfirm(message, content, docSchema)"
+        :on-shortcut-confirm="formModel => handleUserShortcutConfirm(message, formModel)"
+        :on-interrupt-resume="onInterruptResume"
+      />
+    </template>
+  </ChatContainer>
+</template>
 ```
 
 ## API
 
 ### Props
 
-| 属性名             | 类型                                                                         | 说明                                                      |
-| ------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------- |
-| content            | `string \| InputContent[]`                                                   | 消息内容，字符串或含 text/binary 的数组                   |
-| property           | `{ extra?: MessageExtra }`                                                   | 消息附加属性，包含引用、快捷指令、context 等信息          |
-| messageToolsStatus | `MessageToolsStatus`                                                         | 工具按钮状态，`disabled` 禁用、`hidden` 从 DOM 移除       |
-| onAction           | `(tool: IToolBtn) => Promise<void>`                                          | 工具按钮回调；`copy`/`edit` 有内置行为，`cite` 需外部处理 |
-| onInputConfirm     | `(content: string \| InputContent[], docSchema: TagSchema) => Promise<void>` | 普通消息编辑确认回调                                      |
-| onShortcutConfirm  | `(formModel: Record<string, unknown>) => Promise<void>`                      | 快捷指令消息编辑确认回调                                  |
-| tippyOptions       | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>`   | 自定义工具栏 Tippy 配置，透传给内部 `MessageTools` 组件   |
+| 属性名             | 类型                                                                                       | 说明                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| content            | `string \| InputContent[]`                                                                 | 消息内容，字符串或含 text/binary 的数组                                   |
+| createdAt          | `number \| string`                                                                         | 消息创建时间，经 `MessageTools` 的 `#prepend` 插槽交给 `MessageTime` 渲染在工具图标左侧；无值时不展示 |
+| property           | `{ extra?: MessageExtra; artifacts?: AIFileInfo[] }`                                       | 附加属性；本组件消费 `extra.cite` / `shortcut` / `context`                |
+| messageToolsStatus | `MessageToolsStatus`                                                                       | 工具按钮状态，`disabled` 禁用、`hidden` 从 DOM 移除                       |
+| onAction           | `MessageToolsProps['onAction']`                                                            | 工具回调；`copy`/`edit` 有内置行为，`cite`/`delete` 需外部处理            |
+| onInputConfirm     | `(content: UserMessage['content'], docSchema: TagSchema) => Promise<void>`                 | 普通消息编辑确认回调                                                      |
+| onShortcutConfirm  | `(formModel: Record<string, unknown>) => Promise<void>`                                    | 快捷指令消息编辑确认回调                                                  |
+| tippyOptions       | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>`                 | 自定义工具栏 Tippy 配置，透传给内部 `MessageTools`                        |
+
+### Events / Slots / Expose
+
+无。
 
 ### 全局配置依赖
 
-编辑模式下的 `ChatInput` 会通过 `injectGlobalConfig()` 获取全局配置中的 `supportUpload` 值。需要确保祖先组件（通常是 `ChatContainer`）已调用 `useGlobalConfig()` 注册配置。
+编辑态 `ChatInput` 通过 `injectGlobalConfig()` 读取 `supportUpload`。祖先需已 `useGlobalConfig()`（通常由 `ChatContainer` 注册）。
 
 ## 类型定义
 
 ```typescript
 // 文本内容项
 interface TextInputContent {
-  type: 'text'; // MessageContentType.Text
+  type: 'text';
   text: string;
 }
 
 // 二进制内容项（图片、文件）
 interface BinaryContent {
-  type: 'binary'; // MessageContentType.Binary
+  type: 'binary';
   url?: string;
   mimeType?: string;
   filename?: string;
@@ -325,32 +395,32 @@ interface BinaryContent {
 
 type InputContent = TextInputContent | BinaryContent;
 
-// 消息附加属性
-interface MessageExtra {
-  // 文本引用（字符串）：渲染在气泡外 CiteContent
-  cite?: string;
-
-  // 结构化引用（对象）：渲染在气泡内 KeyValueContent；与 context 配合可重建 ShortcutRender
-  cite?: {
-    title?: string;
-    data: Array<{ key: string; value: string }>;
-  };
-
-  // 快捷指令：编辑时渲染 ShortcutRender（优先于 cite+context 路径）
-  shortcut?: Shortcut;
-
-  // 上下文变量：与结构化 cite 配合，在编辑模式下动态构建 ShortcutComponent[]
+// property.extra（与源码 BaseMessage.property.extra 对齐）
+type MessageExtra = {
+  // 文本引用 或 结构化引用（互斥 union，不是两个同名字段）
+  cite?:
+    | string
+    | {
+        title: string;
+        type: 'structured';
+        data: Array<{ key: string; value: string }>;
+      };
+  command?: string;
+  pause?: boolean;
+  shortcut?: Partial<Shortcut>;
   context?: Array<{
     __key: string;
     __label: string;
     __value: string;
     fillBack?: boolean;
+    context_type?: string;
   }>;
-}
+};
 ```
 
 ## 关联组件
 
 - [MessageRender](/components/message/message-render) — user 角色由其实例化
 - [MessageTools](/components/feedback/message-tools) — 工具栏交互
+- [MessageTime](/components/feedback/message-time) — 工具栏左侧的消息时间
 - [MessageContainer](/components/setup/message-container) — 列表与多选容器

package/dist/mcp/generated/docs/user-question-card.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-card.vue。
+渲染 UserQuestion 中断的待回答面板：一次只展示一题，标题栏提供题号切换， Footer 展示已完成进度；支持单选自动跳下一题、多选/Others、完成与跳过。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-card.vue。
 
 ### 关联组件
 - **interrupt-message** — outcome.success 时挂载 UserQuestionAnsweredCard 回显回答
@@ -16,7 +16,7 @@
 
 - **源码位置**：`src/components/chat-message/interrupt-message/user-question/user-question-card.vue`
 - **能力域**：Agent 能力
-- **能力说明**：渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。
+- **能力说明**：渲染 UserQuestion 中断的待回答面板；一次一题分页切换，支持单选/多选、Others、跳过与已完成进度。
 
 > **能力域**：Agent 能力
 
@@ -24,6 +24,9 @@
 
 ## 交互能力
 
+- **一次一题**：正文只展示当前题；标题栏右侧提供 `< 当前题 / 总题数 >` 切换定位（单题为 `1 / 1`），首末题对应箭头禁用。
+- **自动跳转**：单选预设选项从未答变为有效答时，自动跳到下一题（最后一题停留）；多选与 Others 不自动跳，靠箭头切换。
+- **已完成进度**：Footer 左侧展示「已完成 N 题」；右侧为「跳过」+「完成」。
 - **单选 / 多选**：每道题通过 `multiSelect` 控制选择行为；未传时不展示单选/多选标签，默认仍按单选处理。
 - **Others 自由输入**：默认 [UserQuestionChoice](/components/agent/user-question-choice) 为每道题追加 `label: 'others'` 输入项，输入文本写入 `answer[].description`。
 - **自定义作答形态**：通过 `#question` slot 可替换默认选择题，渲染任意表单；作答有效时调用 `setAnswer` 回传 `UserQuestionAnswerItem`，无效时传 `undefined`。
@@ -142,7 +145,7 @@ const payload = {
 />
 ```
 
-- 卡片内「完成 / 跳过」→ `onInterruptResume(payload, interrupt)`
+- 卡片内「跳过 / 完成」→ `onInterruptResume(payload, interrupt)`（Footer 右置，跳过在前、完成在后）
 - 输入框直接发送 → `onSendMessage(content, docSchema, { interrupt, payload })`，其中 `payload` 由 `buildSkipResumePayload(interrupt)` 生成（`status: 'cancelled'`）
 
 ## 工具函数 buildSkipResumePayload