@blueking/chat-x 0.0.51 → 0.0.52-dev.2

package/skills/blueking-chat-x/references/components/user-feedback.md

@@ -0,0 +1,233 @@
+# UserFeedback 用户反馈
+
+> 能力域：工具与反馈 ｜ 导入：`import { MessageUserFeedback } from '@blueking/chat-x'` ｜ since 1.0.0
+
+用户反馈弹层，提交踩/反馈原因。 源码位置：src/components/message-tools/user-feedback/user-feedback.vue。
+
+**关联**：message-tools（点赞/踩操作触发并收集反馈）
+
+---
+
+# MessageUserFeedback 用户反馈
+## 源码事实
+
+- **源码位置**：`src/components/message-tools/user-feedback/user-feedback.vue`
+- **能力域**：工具与反馈
+- **能力说明**：用户反馈弹层，提交踩/反馈原因。
+
+> **能力域**：工具与反馈
+
+AI 消息点赞/踩后收集用户具体反馈原因的弹出面板。支持多选预设原因标签、补充文字说明（textarea）、异步加载原因列表（骨架屏）。
+
+> **通常不需要直接使用。** `MessageTools` 在用户点击 `like`/`unlike` 工具按钮时，会通过内置 Tippy 弹出层自动呈现本组件，并驱动 `loading` 和 `reasonList`。
+
+## 组件结构
+
+```
+.ai-user-feedback（width: 400px，padding: 16px，gap: 16px）
+├── .ai-feedback-title（font-size: 16px，color: #313238）
+│     props.title
+│
+├── .ai-feedback-reason-list（flex-wrap，gap: 4px）
+│     loading=true  → 8 × .reason-item.ai-skeleton-element（每项 width: 70px）
+│     loading=false → v-for reasonList → .reason-item
+│                       is-active（已选）：color #1768ef，bg #e1ecff
+│                       :hover        ：同上（与 is-active 共享样式）
+│
+├── .ai-feedback-other
+│     bkui-vue Input（type=textarea，rows=3，placeholder="说出您的想法"）
+│     → v-model 绑定内部 shallowRef otherReason
+│
+└── .ai-feedback-footer（justify-content: flex-end，gap: 8px）
+      Button primary "提交"（width: 64px，disabled：selectedReasons 空且 otherReason 空）
+      Button default "取消"（width: 64px）
+```
+
+## 基础用法
+
+```vue
+<template>
+  <MessageUserFeedback
+    title="什么原因让你满意？"
+    :reason-list="reasonList"
+    @submit="handleSubmit"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageUserFeedback } from '@blueking/chat-x';
+
+  const reasonList = ['回答准确', '信息全面', '表达清晰', '解决了问题', '示例恰当'];
+
+  const handleSubmit = (selectedReasons: string[], otherReason: string) => {
+    // selectedReasons: 当前已勾选的原因（提交后组件不自动清空）
+    // otherReason: textarea 中的补充说明（可为空字符串）
+    console.log('已选原因:', selectedReasons, '补充说明:', otherReason);
+  };
+
+  const handleCancel = () => {
+    // cancel 触发前组件已清空 selectedReasons 和 otherReason
+    console.log('用户取消了反馈');
+  };
+</script>
+```
+
+**满意反馈**
+
+**不满意反馈**
+
+## 加载状态
+
+原因列表通常需要异步获取，将 `loading` 设为 `true` 时渲染 **8 个**骨架屏占位块（固定数量，与 `reasonList` 无关），数据就绪后切换为 `false`：
+
+```vue
+<template>
+  <MessageUserFeedback
+    title="什么原因让你满意？"
+    :reason-list="reasonList"
+    :loading="isLoading"
+    @submit="handleSubmit"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MessageUserFeedback } from '@blueking/chat-x';
+
+  const isLoading = ref(true);
+  const reasonList = ref<string[]>([]);
+
+  async function fetchReasons() {
+    isLoading.value = true;
+    try {
+      reasonList.value = await fetchFeedbackReasons();
+    } finally {
+      isLoading.value = false;
+    }
+  }
+</script>
+```
+
+**骨架屏效果**
+
+## 交互说明
+
+| 操作         | 行为说明                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------- |
+| 点击原因标签 | **多选**，高亮（`is-active`）；再次点击取消选中；hover 效果与选中态相同                                       |
+| 填写补充说明 | 可选；不选任何标签时，仅有补充说明文本也可解锁提交按钮                                                        |
+| 点击提交     | `selectedReasons.length === 0 && otherReason === ''` 时禁用；点击后触发 `submit` 事件，**组件不自动清空状态** |
+| 点击取消     | 先将 `selectedReasons` 和 `otherReason` 清空（两者均重置），再触发 `cancel` 事件                              |
+
+> **提交与取消的状态差异**：点击"提交"后内部 `selectedReasons` / `otherReason` **不重置**，由父组件决定后续行为（如关闭弹层）；点击"取消"则**立即重置**两者，再触发事件。
+
+## 与 MessageTools 配合使用
+
+`MessageUserFeedback` 在实际场景中由 `MessageTools` 驱动，整体流程：
+
+```
+用户点击 like / unlike
+    ↓
+MessageTools 内部：loading=true，弹出反馈面板（骨架屏）
+    ↓
+调用 onAction(tool) → 返回 string[]（支持 async）
+    ↓
+loading=false，展示原因标签列表
+    ↓
+用户选择原因 → 点击提交
+    ↓
+触发 onAgentFeedback(tool, messages, reasonList, otherReason)
+```
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :on-agent-action="handleAgentAction"
+    :on-agent-feedback="handleFeedback"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageContainer, type IToolBtn, type Message } from '@blueking/chat-x';
+
+  const messages: Message[] = [
+    /* ... */
+  ];
+
+  // 点击 like/unlike 时调用，返回原因列表（支持异步）
+  const handleAgentAction = async (tool: IToolBtn): Promise<string[]> => {
+    if (tool.id === 'like') {
+      return ['回答准确', '信息全面', '表达清晰', '解决了问题'];
+    }
+    if (tool.id === 'unlike') {
+      return ['信息错误', '回答不相关', '解释不清楚', '没有解决问题'];
+    }
+    return [];
+  };
+
+  // 用户提交反馈后触发
+  const handleFeedback = (tool: IToolBtn, messages: Message[], reasonList: string[], otherReason: string) => {
+    console.log(`${tool.id} 反馈:`, { reasonList, otherReason });
+    // 上报到后端
+  };
+</script>
+```
+
+若需在自定义位置独立使用，可配合 `vue-tippy`：
+
+```vue
+<template>
+  <Tippy
+    :arrow="false"
+    interactive
+    trigger="click"
+    theme="ai-chat-box-light light"
+    :offset="[0, 6]"
+    :append-to="() => document.body"
+  >
+    <button>👍 点赞</button>
+    <template #content>
+      <MessageUserFeedback
+        title="什么原因让你满意？"
+        :reason-list="reasonList"
+        :loading="isLoading"
+        @submit="handleSubmit"
+        @cancel="handleCancel"
+      />
+    </template>
+  </Tippy>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名     | 类型       | 必填 | 默认值  | 说明                                                   |
+| ---------- | ---------- | ---- | ------- | ------------------------------------------------------ |
+| title      | `string`   | ✓    | —       | 面板标题文本                                           |
+| reasonList | `string[]` | ✓    | —       | 预设原因标签列表；`loading=true` 时列表不渲染          |
+| loading    | `boolean`  | —    | `false` | `true` 时显示 8 个骨架屏占位块，隐藏 `reasonList` 内容 |
+
+### Events
+
+| 事件名 | 参数签名                                      | 触发时机                                                    |
+| ------ | --------------------------------------------- | ----------------------------------------------------------- |
+| submit | `(reasonList: string[], otherReason: string)` | 点击提交按钮时（至少一项原因或补充说明不为空）              |
+| cancel | —                                             | 点击取消按钮时（内部已重置 selectedReasons 和 otherReason） |
+
+### 内部状态
+
+以下为组件内部 `shallowRef` 状态，不暴露为 props/emits：
+
+| 状态名          | 类型       | 说明                                        |
+| --------------- | ---------- | ------------------------------------------- |
+| selectedReasons | `string[]` | 当前已选原因列表；取消时重置，提交时不重置  |
+| otherReason     | `string`   | textarea 补充说明；取消时重置，提交时不重置 |
+
+## 关联组件
+
+- [MessageTools](/components/feedback/message-tools) — 点赞/踩入口与反馈联动

package/skills/blueking-chat-x/references/components/user-message.md

@@ -0,0 +1,444 @@
+# UserMessage 用户消息
+
+> 能力域：消息系统 ｜ 未从包入口导出：内部组件（入口的同名导出是 TS 类型，不是组件） ｜ since 0.0.20
+
+渲染用户消息：纯文本（非 Markdown）、键值引用、二进制附件与编辑态 ChatInput / ShortcutRender； 正文经 CollapsibleContent 限高 200px，property.docSchema 含标签时改用 MentionText 还原资源标签； 工具栏含 copy / edit / delete。源码位置：src/components/chat-message/user-message/user-message.vue。
+
+**关联**：mention-text（文档含标签时用它还原已选资源）、collapsible-content（正文超过 200px 时折叠）、message-render（由 MessageRender 在 role 为 user 时创建）、message-tools（消息工具栏交互与状态由 MessageTools 体系承载）、message-time（createdAt 经工具栏 prepend 插槽展示）、message-container（嵌入列表时由 MessageContainer 管理分组与多选）、chat-input（编辑态普通消息使用 ChatInput）
+
+---
+
+# UserMessage 用户消息
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/user-message/user-message.vue`
+- **能力域**：消息系统
+- **能力说明**：渲染用户消息：纯文本、键值引用、文件附件与编辑态输入（**不**渲染 Markdown）。
+
+> **导出说明**：`UserMessage` **未**从 `@blueking/chat-x` 包入口导出（入口同名是 TS interface）。消费方请用 `MessageRender` / `MessageContainer`。下文 `UserMessageComp` 为文档站内部相对路径示例。
+
+用户消息展示组件，右对齐。支持纯文本、多媒体（图片/文件）、文本引用、结构化引用、快捷指令，以及内联编辑。
+
+## 组件结构
+
+**正常模式**
+
+```
+.ai-user-message（align-items: flex-end，gap: 6px，font-size: 12px）
+├── CiteContent（v-if：cite 为字符串）
+│     紧凑条带（高 28px，灰色 #f5f7fa），引用图标 + 单行截断文本
+│
+├── [Binary 图片区] v-if binaryImageFiles.length
+│     .ai-user-message-binary-files → FileContent（readonly=true，图片统一渲染，支持点击预览）
+│
+├── [Binary 非图片文件区] v-for binaryNonImageFiles
+│     .ai-user-message-binary-files → FileContent（readonly=true，每个文件独立渲染）
+│
+├── .ai-user-message-content（气泡：bg #e1ecff，padding 8×12，border-radius 4px）
+│   └── CollapsibleContent（maxHeight = CONST_USER_MESSAGE_MAX_HEIGHT，200px）
+│         v-if: cite 为数组   → KeyValueContent（title + key/value 列表）
+│         v-else-if: 文档含标签 → MentionText（还原 @ 选中的资源）
+│         v-else-if: content   → TextContent × N（textParts 中每个文本片段一个实例）
+│
+└── MessageTools（.ai-user-message-tools）
+      v-if: messageToolsStatus !== 'hidden'
+      visibility: hidden（默认）→ visible（:hover 时）
+      tools: [copy, edit, delete]，updateTools: []
+      #prepend slot → MessageTime（createdAt，工具图标左侧）
+```
+
+> **时间随工具栏显隐**：时间位于工具栏内，与工具按钮共用 `visibility` 控制，因此同样在悬停消息时才可见。
+
+**编辑模式**（点击 `edit` 按钮后 `isEdit=true`）
+
+```
+.ai-user-message
+├── CiteContent（同上，不受编辑模式影响）
+│
+├── ShortcutRender（v-if: shortcut 有值）
+│     @close → isEdit=false
+│     @submit(formModel) → onShortcutConfirm(formModel) + isEdit=false
+│
+└── ChatInput（v-else，带自定义 #send-icon slot）
+      v-model: editContent（有富文本文档时用文档回填，否则取 textParts[0]）
+      defaultUploadFiles: binaryFiles
+      menuSources: injectGlobalConfig().menuSources
+      #send-icon slot → .user-edit-footer
+            Button "取消" → isEdit=false
+            Button primary "发送" → chatInputRef.triggerSendMessage() + isEdit=false
+```
+
+## 资源标签回显与正文折叠
+
+**标签回显**：`property.docSchema` 是发送时输入框的富文本文档。**只有文档里真的含标签节点时**才走 [MentionText](/components/rendering/mention-text) 结构化渲染，纯文本文档仍走 `TextContent`——历史消息与第三方消息的表现因此保持不变。`content` 始终是纯文本，后端契约不变。
+
+**附件标签不重复展示**：`ChatInput` 发送时会把待发送附件补成 `artifact` 标签写进文档，本组件在渲染与编辑回填前会剥掉 `value` 命中当前附件的那些标签（`outputId` 与 `id` 都参与匹配，历史消息经 chat-helper 转换后只剩 `id`），同一文件只由 `FileContent` 卡片承载。整行标签被剥掉后不留空行，用户手输的空行照常保留；`@` 选中的其它资源、以及没有附件承载的 `artifact` 标签都照常回显。
+
+编辑态同样以 `docSchema` 回填，否则改完这条消息已选资源会退化成纯文本；因此业务侧在 `onInputConfirm` 里要把新的 `docSchema` 一起写回。
+
+**正文折叠**：正文外层套 [CollapsibleContent](/components/rendering/collapsible-content)，超过 `CONST_USER_MESSAGE_MAX_HEIGHT`（200px）时折叠并展示「显示更多 / 收起」。
+
+**编辑态自动聚焦**：点击 `edit` 后编辑态输入框才开始渲染，组件在 `nextTick` 后调用 `focus()`，光标落到已有内容末尾。
+
+## 基础用法
+
+`content` 为字符串时，通过 `TextContent` 以**纯文本**插值渲染（`{{ content }}`），**不**走 Markdown。
+
+```vue
+<template>
+  <MessageRender
+    :message="message"
+    :on-action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+  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 有内置行为；delete 需业务侧处理
+    console.log('工具操作:', tool.id);
+  };
+</script>
+```
+
+> **工具栏**：悬停时显示「复制」「编辑」「删除」（CSS `visibility`，始终占位）。
+
+## 多媒体消息
+
+`content` 为数组时，同时支持文本（`type: 'text'`）和二进制文件（`type: 'binary'`）。组件将 `binary` 项按图片和非图片分为两组：
+
+- **图片文件**（`binaryImageFiles`）：判断 `url` 存在或 `mimeType` / `file.type` 以 `image/` 开头的文件，统一放入一个 `FileContent`（`readonly=true`）中渲染，支持点击缩略图全屏预览
+- **非图片文件**（`binaryNonImageFiles`）：每个文件单独渲染在 `FileContent`（`readonly=true`）中
+
+`text` 项经 `textParts` 计算属性统一为 `string[]`，按顺序各渲染一个 `TextContent`。
+
+```vue
+<script setup lang="ts">
+  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>
+```
+
+## 带引用的消息
+
+通过 `property.extra.cite` 传入引用内容，支持两种格式，渲染位置不同：
+
+| `cite` 类型               | 渲染组件                                         | 渲染位置         |
+| ------------------------- | ------------------------------------------------ | ---------------- |
+| `string`                  | `CiteContent`（紧凑条带，高 28px，文本单行截断） | 气泡**外部上方** |
+| `{ title?, data[] }` 对象 | `KeyValueContent`（键值对列表）                  | 气泡**内部**     |
+
+### 文本引用
+
+`cite` 为字符串时，在气泡上方显示一个带引用图标的灰色条带（`#f5f7fa`），文本过长时截断。
+
+```vue
+<script setup lang="ts">
+  // 消费方将 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>
+```
+
+### 结构化引用（键值对）
+
+`cite` 为对象 `{ title?, data: { key, value }[] }` 时，引用内容渲染在气泡**内部**（`KeyValueContent` 组件）：
+
+```vue
+<script setup lang="ts">
+  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 条' },
+          ],
+        },
+      },
+    },
+  };
+</script>
+```
+
+## 快捷指令消息
+
+当消息来自快捷指令时，`property.extra.shortcut` 中携带快捷指令对象。在**编辑模式**下，组件渲染 `ShortcutRender` 代替普通 `ChatInput`。
+
+`shortcut` computed 支持两条来源路径：
+
+```
+1. property.extra.shortcut 有值 → 直接使用
+2. property.extra.cite 为对象 + property.extra.context 有值
+     → 从 cite.data 和 context 动态构建 ShortcutComponent[] 数组
+```
+
+```vue
+<script setup lang="ts">
+  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: '请帮我翻译这段文字' },
+        },
+      },
+    },
+  };
+</script>
+```
+
+## 消息编辑
+
+点击「编辑」按钮后进入编辑模式，根据消息类型呈现不同界面：
+
+| 消息类型                                     | 编辑界面                                              | 确认回调            |
+| -------------------------------------------- | ----------------------------------------------------- | ------------------- |
+| 普通文本 / 含文件消息                        | `ChatInput`（自定义 `#send-icon`，含"取消/发送"按钮） | `onInputConfirm`    |
+| 含 `property.extra.shortcut` 或 cite+context | `ShortcutRender`                                      | `onShortcutConfirm` |
+
+**`editContent` 的初始化逻辑**（仅文本部分，二进制文件通过 `defaultUploadFiles` 恢复）：
+
+```
+文档含标签      → editContent = property.docSchema（保留已选资源）
+否则 textParts 有值 → editContent = textParts[0]（取第一个文本片段）
+binaryFiles 有值   → 进入编辑模式（editContent 可为空）
+进入编辑态后       → nextTick 后自动 focus，光标落在内容末尾
+```
+
+`textParts` 由 `content` 统一计算：`string` 转为单元素数组，`InputContent[]` 则过滤出 `type: 'text'` 且非空的项并映射为 `string[]`。
+
+```vue
+<template>
+  <MessageRender
+    :message="message"
+    :on-action="handleAction"
+    :on-input-confirm="handleInputConfirm"
+    :on-shortcut-confirm="handleShortcutConfirm"
+  />
+</template>
+
+<script setup lang="ts">
+  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) => {
+    // edit → 组件内切编辑态；copy → 组件内复制
+    // delete → 无内置行为，业务侧处理（如删除会话消息）
+    console.log('工具:', tool.id);
+  };
+
+  const handleInputConfirm = async (content: UserMessage['content'], docSchema: TagSchema) => {
+    console.log('编辑后内容:', content, docSchema);
+  };
+
+  const handleShortcutConfirm = async (formModel: Record<string, unknown>) => {
+    console.log('快捷指令表单:', formModel);
+  };
+</script>
+```
+
+## 工具按钮
+
+工具栏使用 CSS `visibility` 控制可见性（非 `display`），始终占位，hover 时显示：
+
+**内置工具列表（`CONST_USER_MESSAGE_TOOLS`）**
+
+| 工具 ID  | 名称 | 内置行为                                     |
+| -------- | ---- | -------------------------------------------- |
+| `copy`   | 复制 | 字符串直接复制；数组 `JSON.stringify` 后复制 |
+| `edit`   | 编辑 | 切换 `isEdit=true`，进入编辑模式并自动聚焦   |
+| `delete` | 删除 | 无内置行为，需通过 `onAction` 外部处理       |
+
+> `cite`（引用）已从内置列表移除，后续不再支持；需要类似能力时通过 `messageTools` 自行追加按钮并在 `onAction` 中处理。
+
+可通过 `messageTools` 按 id 覆盖/追加，`{ id: 'edit', hidden: true }` 可隐藏内置项。
+
+```vue
+<!-- 经 MessageRender 控制工具栏状态 -->
+<MessageRender
+  :message="message"
+  message-tools-status="hidden"
+/>
+<MessageRender
+  :message="message"
+  message-tools-status="disabled"
+/>
+```
+
+## 全局配置透传
+
+编辑态 `ChatInput` 的上传能力与菜单数据源都来自 `injectGlobalConfig()`——`supportUpload` 与 `menuSources`（通常由 `ChatContainer` 注册）。自定义 `#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 的数组                                   |
+| createdAt          | `number \| string`                                                                         | 消息创建时间，经 `MessageTools` 的 `#prepend` 插槽交给 `MessageTime` 渲染在工具图标左侧；无值时不展示 |
+| property           | `{ docSchema?: TagSchema; extra?: MessageExtra; artifacts?: AIFileInfo[] }`                                       | 附加属性；本组件消费 `docSchema` 与 `extra.cite` / `extra.shortcut` / `extra.context`  |
+| messageTools       | `IToolBtn[]`                                                                               | 自定义用户消息工具组；按 id 与 `CONST_USER_MESSAGE_TOOLS` 合并，`{ id, hidden: true }` 可隐藏 |
+| messageToolsStatus | `MessageToolsStatus`                                                                       | 工具按钮状态，`disabled` 禁用、`hidden` 从 DOM 移除                       |
+| onAction           | `MessageToolsProps['onAction']`                                                            | 工具回调；`copy`/`edit` 有内置行为，`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` 与 `menuSources`（缺省为空数组，即编辑态无菜单）。祖先需已 `useGlobalConfig()`（通常由 `ChatContainer` 注册）。
+
+## 类型定义
+
+```typescript
+// 文本内容项
+interface TextInputContent {
+  type: 'text';
+  text: string;
+}
+
+// 二进制内容项（图片、文件）
+interface BinaryContent {
+  type: 'binary';
+  url?: string;
+  mimeType?: string;
+  filename?: string;
+}
+
+type InputContent = TextInputContent | BinaryContent;
+
+// 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 角色由其实例化
+- [MentionText](/components/rendering/mention-text) — 含标签文档的回显
+- [CollapsibleContent](/components/rendering/collapsible-content) — 正文 200px 折叠
+- [MessageTools](/components/feedback/message-tools) — 工具栏交互
+- [MessageTime](/components/feedback/message-time) — 工具栏左侧的消息时间
+- [MessageContainer](/components/setup/message-container) — 列表与多选容器