@blueking/chat-x 0.0.5 → 0.0.7

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

@@ -0,0 +1,625 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ChatInput 是聊天主输入区，集成富文本编辑（/ 提示词模板、@ 资源引用）、消息引用、附件上传与快捷指令入口。 通过 prompts、resources、shortcuts 等 props 配置能力，配合 messageStatus 控制发送、流式与停止。 内部组合 ShortcutBtns、FileUploadBtn 等，与 ShortcutRender 联动完成含表单的快捷指令流程。
+
+### 关联组件
+- **shortcut-btns** — 底部附件区默认展示的快捷指令列表
+- **shortcut-btn** — 已选快捷指令以单按钮形式展示并可关闭
+- **shortcut-render** — 快捷指令含 components 时由外层唤起表单渲染
+- **chat-container** — 顶层聊天布局中作为输入区子组件
+- **cite-content** — 消息引用区展示选中的上下文片段
+
+---
+<!-- FULL DOC -->
+
+# ChatInput 聊天输入框
+
+> **层级**：分子组件 · **功能域**：输入交互
+
+聊天消息输入框组件，支持快捷指令选择、资源 `@` 引用、Prompt `/` 模板、消息引用、文件上传（拖拽/粘贴/点击）等功能。
+
+## 组件结构
+
+```
+chat-input-container
+├── slot#top（容器顶部，在输入框框体外侧）
+└── chat-input（框体，受 inputMaxHeight 控制）
+    ├── slot#input-header（默认：cite 不为空时渲染引用区）
+    ├── slot#files（默认：有上传文件时渲染文件预览区）
+    ├── AiSlashInput（富文本编辑器，/ 触发 Prompt，@ 触发资源）
+    └── InputAttachment（底部工具栏，高度固定 40px）
+        ├── FileUploadBtn（仅当 supportUpload 为 true 时显示，在 slot#attachment 外部）
+        ├── 分隔线（仅当 supportUpload 为 true 且有快捷指令时显示）
+        ├── slot#attachment（默认：ShortcutBtns 或已选 ShortcutBtn + 关闭图标）
+        └── slot#send-icon（默认：发送/停止图标，仅替换图标，按钮容器保留）
+```
+
+> **注意**：`slot#attachment` 只替换快捷指令区，`FileUploadBtn` 在其外部，使用该 slot 不会移除上传按钮。`slot#send-icon` 只替换图标，按钮的点击处理和样式仍由组件控制。
+
+## 基础用法
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    :message-status="messageStatus"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatInput, MessageStatus, type TagSchema } from '@blueking/chat-x';
+
+  const inputValue = ref('');
+  const messageStatus = ref(MessageStatus.Complete);
+
+  const handleSendMessage = async (content: string, docSchema: TagSchema) => {
+    // content：纯文本字符串（无文件时）或 InputContent[] 数组（有文件时）
+    messageStatus.value = MessageStatus.Streaming;
+    // ... 发送 AI 请求
+    messageStatus.value = MessageStatus.Complete;
+  };
+
+  const handleStopSending = async () => {
+    messageStatus.value = MessageStatus.Stop;
+  };
+</script>
+```
+
+**渲染效果**（输入 `/` 唤出 Prompt，输入 `@` 唤出资源菜单）
+
+## 发送状态（messageStatus）
+
+`messageStatus` 控制底部工具栏的按钮渲染，但**输入框为空时始终自动置灰禁用**，无论 `messageStatus` 传入什么值。
+
+| `messageStatus`               | 输入框有内容时按钮表现                                 | 输入框空时               |
+| ----------------------------- | ------------------------------------------------------ | ------------------------ |
+| `complete` / `stop` / `error` | 蓝色发送按钮，点击触发 `onSendMessage`                 | 灰色禁用                 |
+| `streaming` / `pending`       | 蓝色停止按钮（Loading 图标），点击触发 `onStopSending` | 蓝色停止按钮（仍可点击） |
+| `disabled`                    | 灰色禁用，点击无效                                     | 灰色禁用                 |
+
+> **实现细节**：组件内部用 `messageState` 计算属性决定实际按钮状态：当 `messageStatus` 为 `pending` 或 `streaming` 时直接使用该状态（确保停止按钮始终可用）；否则当输入为空或仅含空白字符时强制为 `disabled`，其余情况使用 `messageStatus` 的值。
+
+### Complete（可发送）
+
+### Streaming（流式输出中，显示停止按钮）
+
+### Disabled（禁用）
+
+## 引用消息（v-model:cite）
+
+通过 `v-model:cite` 绑定引用内容，引用区域显示在编辑器上方，用户可点击关闭按钮取消引用。发送时通过 `onSendMessage` 的第一个参数获取输入内容，引用内容需自行通过 `cite` 变量读取：
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    v-model:cite="citeContent"
+    :message-status="messageStatus"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatInput, MessageStatus, type TagSchema } from '@blueking/chat-x';
+
+  const inputValue = ref('');
+  const citeContent = ref('被引用的消息内容...');
+  const messageStatus = ref(MessageStatus.Complete);
+
+  const handleSendMessage = async (content: string, docSchema: TagSchema) => {
+    console.log('输入内容:', content);
+    console.log('引用内容:', citeContent.value); // 自行读取引用内容
+    citeContent.value = ''; // 发送后清空引用
+  };
+
+  const handleStopSending = async () => {
+    messageStatus.value = MessageStatus.Stop;
+  };
+</script>
+```
+
+**渲染效果**（顶部引用区，点击右侧 × 关闭引用）
+
+## Prompt 模板（`/` 触发）
+
+通过 `prompts` 传入字符串数组，用户在编辑器中输入 `/` 唤出 Prompt 菜单，支持模糊搜索，选择后自动填入编辑器：
+
+```vue
+<script setup lang="ts">
+  const prompts = [
+    '帮我写一篇关于 {topic} 的文章',
+    '解释一下这段代码的作用',
+    '请用简洁的语言总结以下内容',
+    '将以下内容翻译成英文',
+    '帮我优化这段代码',
+  ];
+</script>
+```
+
+## 资源 `@` 引用（`@` 触发）
+
+通过 `resources` 传入资源列表，用户输入 `@` 唤出资源选择菜单。资源按 `type` 分组展示，选中后以 Tag 标签形式嵌入编辑器。已选中的资源不会再出现在下拉菜单中（自动去重）。
+
+通过监听 `@update:model-value` 事件的第二个参数 `selectedResourceList` 可以获取当前编辑器中已选中的资源列表：
+
+```vue
+<template>
+  <ChatInput
+    :model-value="inputValue"
+    :message-status="messageStatus"
+    :prompts="prompts"
+    :resources="resources"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+    @update:model-value="handleModelValueUpdate"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatInput, MessageStatus, type TagSchema, type IAiSlashMenuItem } from '@blueking/chat-x';
+
+  const inputValue = ref('');
+  const messageStatus = ref(MessageStatus.Complete);
+
+  const resources: IAiSlashMenuItem[] = [
+    { id: 'tool1', name: '天气查询', type: 'tool', icon: 'icon-tool' },
+    { id: 'tool2', name: '代码执行', type: 'tool', icon: 'icon-tool' },
+    { id: 'mcp1', name: 'db-server', type: 'mcp', icon: 'icon-mcp' },
+    { id: 'doc1', name: 'API 文档', type: 'doc', icon: 'icon-doc' },
+    { id: 'sc1', name: '翻译助手', type: 'shortcut', icon: 'icon-shortcut' },
+  ];
+
+  const handleModelValueUpdate = (value: string | TagSchema, selectedResourceList: IAiSlashMenuItem[]) => {
+    inputValue.value = value;
+    // selectedResourceList 为当前编辑器中已选中的 @ 资源列表
+    console.log('已选资源:', selectedResourceList);
+  };
+
+  const handleSendMessage = async (content: string, docSchema: TagSchema) => {
+    console.log('发送内容（含 @ 引用）:', docSchema);
+  };
+
+  const handleStopSending = async () => {
+    messageStatus.value = MessageStatus.Stop;
+  };
+</script>
+```
+
+> 基础用法 demo 已集成 Prompt 和资源功能，可在上方输入框中体验 `/` 和 `@` 操作。
+>
+> **注意**：`v-model` 仍可使用（Vue 自动取第一个参数绑定），但如需获取 `selectedResourceList`，应使用 `@update:model-value` 显式监听。
+
+## 快捷指令
+
+通过 `shortcuts` 传入快捷指令列表，底部工具栏展示快捷指令按钮；通过 `shortcutId` + `shortcuts` 配合控制选中状态：
+
+- `shortcutId` 为空 → 显示所有快捷指令按钮列表
+- `shortcutId` 匹配某个 `shortcut.id` → 隐藏列表，显示已选指令 + 关闭图标
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    :message-status="messageStatus"
+    :shortcuts="shortcuts"
+    :shortcut-id="selectedShortcutId"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+    @select-shortcut="selectedShortcutId = $event.id"
+    @delete-shortcut="selectedShortcutId = ''"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatInput, MessageStatus, type TagSchema, type Shortcut } from '@blueking/chat-x';
+
+  const inputValue = ref('');
+  const messageStatus = ref(MessageStatus.Complete);
+  const selectedShortcutId = ref('');
+
+  const shortcuts: Shortcut[] = [
+    { id: 'translate', name: '翻译' },
+    { id: 'explain', name: '解释代码' },
+    { id: 'summarize', name: '总结' },
+  ];
+
+  const handleSendMessage = async (content: string, docSchema: TagSchema) => {
+    console.log('发送内容:', content, '当前快捷指令:', selectedShortcutId.value);
+  };
+
+  const handleStopSending = async () => {
+    messageStatus.value = MessageStatus.Stop;
+  };
+</script>
+```
+
+**渲染效果**（底部显示快捷指令按钮，点击选中后按钮变为已选状态）
+
+## 文件上传
+
+`supportUpload` 默认为 `true`，底部工具栏自动显示文件上传按钮。传入 `onUpload` 回调后即可处理文件上传：
+
+- 底部工具栏出现文件上传按钮（在快捷指令左侧）
+- 支持**点击选择**、**拖拽上传**、**粘贴上传**（Ctrl+V）
+- `onUpload` 每次传入**单个** `File`，返回 `{ download_url?: string }`
+- 文件自动去重（基于 `name + size + lastModified` 复合键），不会重复上传
+- 发送成功后，`uploadFiles` 自动清空
+
+**发送内容格式**（有文件时）：
+
+```typescript
+// onSendMessage 的 content 参数变为数组：
+[
+  { type: 'binary', url: '...', mimeType: 'image/png', filename: 'a.png' },
+  { type: 'binary', url: '...', mimeType: 'application/pdf', filename: 'b.pdf' },
+  // 若输入框也有文字，则最后追加：
+  { type: 'text', text: '请帮我分析这两个文件' },
+];
+```
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    :message-status="messageStatus"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+    :on-upload="handleUpload"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatInput, MessageStatus, type UserMessage, type TagSchema } from '@blueking/chat-x';
+
+  const inputValue = ref('');
+  const messageStatus = ref(MessageStatus.Complete);
+
+  const handleSendMessage = async (content: UserMessage['content'], docSchema: TagSchema) => {
+    if (Array.isArray(content)) {
+      // 有文件时 content 为数组
+      content.forEach(item => {
+        if (item.type === 'binary') console.log('文件:', item.filename, item.url);
+        if (item.type === 'text') console.log('文字:', item.text);
+      });
+    } else {
+      // 无文件时 content 为纯字符串
+      console.log('文字:', content);
+    }
+  };
+
+  const handleStopSending = async () => {
+    messageStatus.value = MessageStatus.Stop;
+  };
+
+  // 每次传入单个 File，需返回 { download_url: string }
+  const handleUpload = async (file: File) => {
+    const formData = new FormData();
+    formData.append('file', file);
+    const res = await fetch('/api/upload', { method: 'POST', body: formData });
+    return res.json(); // { download_url: '...' }
+  };
+</script>
+```
+
+**渲染效果**（底部出现文件上传按钮，支持点击、拖拽、粘贴上传）
+
+## 预设上传文件（defaultUploadFiles）
+
+通过 `defaultUploadFiles` 设置初始已上传的文件列表，文件出现在文件预览区，随下次发送一起携带：
+
+```vue
+<script setup lang="ts">
+  import { type UploadFile, UploadStatus } from '@blueking/chat-x';
+
+  const defaultFiles: UploadFile[] = [
+    {
+      type: 'binary',
+      url: 'https://example.com/report.pdf',
+      filename: 'report.pdf',
+      mimeType: 'application/pdf',
+      status: UploadStatus.Success,
+    },
+  ];
+</script>
+```
+
+## 自定义占位符
+
+通过 `placeholder` 自定义占位符文案，支持多行（换行用 `\n`）：
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    :message-status="messageStatus"
+    :placeholder="placeholder"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+  />
+</template>
+
+<script setup lang="ts">
+  // 多行占位符
+  const placeholder = `你好，我是 AI 小鲸！
+输入 "/" 唤出 Prompt
+输入 "@" 唤出工具
+按 Shift + Enter 换行`;
+</script>
+```
+
+**渲染效果**
+
+## 自定义插槽
+
+组件提供 5 个插槽用于自定义各区域内容：
+
+| 插槽名         | 位置                                       | 默认行为                                   |
+| -------------- | ------------------------------------------ | ------------------------------------------ |
+| `top`          | 框体外部顶部（`.chat-input` 上方）         | 无                                         |
+| `input-header` | 框体内部顶部（编辑器上方）                 | `cite` 不为空时渲染引用区（`CiteContent`） |
+| `files`        | 文件预览区                                 | 有上传文件时渲染 `FileContent`             |
+| `attachment`   | 底部工具栏快捷指令区（FileUploadBtn 右侧） | 快捷指令按钮列表 / 已选快捷指令            |
+| `send-icon`    | 发送按钮内的图标                           | 发送图标 / 停止图标（按钮容器由组件控制）  |
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    :message-status="messageStatus"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+  >
+    <!-- 框体外顶部，适合展示模型信息、Token 消耗等 -->
+    <template #top>
+      <div class="input-tips">当前模型: GPT-4 · 剩余 Token: 12,800</div>
+    </template>
+
+    <!-- 替换引用区，可自定义引用样式 -->
+    <template #input-header>
+      <div class="custom-header">自定义头部内容</div>
+    </template>
+
+    <!-- 替换文件预览区，接收 files 参数 -->
+    <template #files="{ files }">
+      <div class="custom-files">
+        <span
+          v-for="file in files"
+          :key="file.filename"
+          >{{ file.filename }}</span
+        >
+      </div>
+    </template>
+
+    <!-- 替换快捷指令区（FileUploadBtn 仍在左侧） -->
+    <template #attachment>
+      <button @click="handleCustomAction">🎯 自定义操作</button>
+    </template>
+
+    <!-- 替换发送按钮图标（点击逻辑不变） -->
+    <template #send-icon>
+      <span>🚀</span>
+    </template>
+  </ChatInput>
+</template>
+```
+
+**渲染效果**（顶部自定义模型信息提示）
+
+## Expose（模板引用）
+
+通过 `ref` 获取组件实例后可调用以下方法：
+
+```vue
+<template>
+  <ChatInput
+    ref="chatInputRef"
+    v-model="inputValue"
+    :on-send-message="handleSendMessage"
+  />
+  <button @click="chatInputRef?.focus()">聚焦输入框</button>
+  <button @click="chatInputRef?.triggerSendMessage()">手动发送</button>
+</template>
+
+<script setup lang="ts">
+  import { useTemplateRef } from 'vue';
+  import { ChatInput } from '@blueking/chat-x';
+
+  const chatInputRef = useTemplateRef<InstanceType<typeof ChatInput>>('chatInputRef');
+  const inputValue = ref('');
+  const handleSendMessage = async (content: string) => {
+    /* ... */
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名             | 类型                                                                       | 默认值   | 必填 | 说明                                                    |
+| ------------------ | -------------------------------------------------------------------------- | -------- | ---- | ------------------------------------------------------- |
+| modelValue         | `string \| TagSchema`                                                      | -        | ✅   | 编辑器的值，支持 `v-model`                              |
+| messageStatus      | `MessageStatus`                                                            | -        | -    | 消息状态，控制按钮；输入为空时内部强制 `disabled`       |
+| cite               | `string`                                                                   | `''`     | -    | 引用内容，支持 `v-model:cite`，不为空时显示引用区       |
+| prompts            | `string[]`                                                                 | `[]`     | -    | Prompt 模板列表，输入 `/` 触发                          |
+| resources          | `IAiSlashMenuItem[]`                                                       | `[]`     | -    | 资源列表，输入 `@` 触发，按 `type` 分组展示             |
+| shortcuts          | `Shortcut[]`                                                               | -        | -    | 快捷指令列表，显示在底部工具栏                          |
+| shortcutId         | `string`                                                                   | -        | -    | 当前选中的快捷指令 ID，匹配时列表收起为已选样式         |
+| placeholder        | `string`                                                                   | 见默认值 | -    | 编辑器占位符，支持多行                                  |
+| inputMaxHeight     | `number`                                                                   | `200`    | -    | 框体最大高度（px），有文件时自动加上文件预览区高度      |
+| defaultUploadFiles | `UploadFile[]`                                                             | -        | -    | 预设已上传的文件列表                                    |
+| supportUpload      | `boolean`                                                                  | `true`   | -    | 是否显示文件上传按钮                                    |
+| tippyOptions       | `AITippyProps`                                                             | —        | -    | 透传给 FileUploadBtn 和 InputAttachment 的 tooltip 配置 |
+| onSendMessage      | `(content: UserMessage['content'], docSchema: TagSchema) => Promise<void>` | -        | -    | 发送消息回调，无文件时 content 为字符串，有文件时为数组 |
+| onStopSending      | `() => Promise<void>`                                                      | -        | -    | 停止发送回调，点击停止按钮时触发                        |
+| onUpload           | `(file: File) => Promise<{ download_url?: string }>`                       | -        | -    | 文件上传回调（每次单文件）                              |
+
+### 默认占位符
+
+```
+输入 "/"唤出 Prompt
+输入"@"唤出工具
+通过 Shift + Enter 进行换行输入
+```
+
+### Events
+
+| 事件名            | 参数                                                                     | 触发时机                                                  |
+| ----------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
+| update:modelValue | `(value: string \| TagSchema, selectedResourceList: IAiSlashMenuItem[])` | 编辑器值变化时触发；第二个参数为当前已选中的 `@` 资源列表 |
+| selectShortcut    | `(shortcut: Shortcut)`                                                   | 点击底部快捷指令按钮                                      |
+| deleteShortcut    | -                                                                        | 点击已选快捷指令旁的关闭按钮                              |
+
+### Slots
+
+| 插槽名       | 参数                               | 说明                                                       |
+| ------------ | ---------------------------------- | ---------------------------------------------------------- |
+| top          | -                                  | 框体（`.chat-input`）外部顶部，适合展示模型/Token 信息     |
+| input-header | -                                  | 框体内顶部，替换引用区（`CiteContent`）                    |
+| files        | `{ files: Partial<UploadFile>[] }` | 文件预览区                                                 |
+| attachment   | -                                  | 底部快捷指令区，`FileUploadBtn` 在其左侧，不受此 slot 影响 |
+| send-icon    | -                                  | 发送按钮内图标，按钮的点击逻辑和样式仍由组件控制           |
+
+### Expose
+
+| 方法名             | 类型         | 说明             |
+| ------------------ | ------------ | ---------------- |
+| focus              | `() => void` | 聚焦编辑器       |
+| triggerSendMessage | `() => void` | 手动触发发送逻辑 |
+
+## 键盘快捷键
+
+| 快捷键          | 说明                                     |
+| --------------- | ---------------------------------------- |
+| `Enter`         | 发送消息（输入为空或仅空白字符时不触发） |
+| `Shift + Enter` | 换行                                     |
+| `/`             | 唤出 Prompt 列表                         |
+| `@`             | 唤出资源列表                             |
+| `↑` / `↓`       | 在 Prompt / 资源菜单中导航               |
+| `Esc`           | 关闭 Prompt / 资源菜单                   |
+
+## 类型定义
+
+```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', // 上传中
+  Success = 'success', // 上传成功
+  Error = 'error', // 上传失败
+}
+
+// 上传文件
+type UploadFile = {
+  type: 'binary';
+  url?: string; // 上传成功后的下载地址
+  filename?: string; // 文件名
+  mimeType?: string; // MIME 类型
+  file?: File; // 原始 File 对象
+  status?: UploadStatus; // 上传状态
+};
+
+// 资源菜单项（@ 触发）
+interface IAiSlashMenuItem {
+  id: string;
+  name: string;
+  icon: string;
+  type: 'tool' | 'mcp' | 'doc' | 'shortcut'; // 分组类型
+}
+
+// onSendMessage 的 content 参数
+type SendContent =
+  | string // 无文件时：纯文本
+  | Array<
+      // 有文件时：数组
+      { type: 'binary'; url?: string; mimeType: string; filename: string } | { type: 'text'; text: string }
+    >;
+```
+
+## 完整集成示例
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    v-model:cite="citeContent"
+    :message-status="messageStatus"
+    :prompts="prompts"
+    :resources="resources"
+    :shortcuts="shortcuts"
+    :shortcut-id="shortcutId"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+    :on-upload="handleUpload"
+    @select-shortcut="shortcutId = $event.id"
+    @delete-shortcut="shortcutId = ''"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatInput, MessageStatus, type TagSchema, type Shortcut } from '@blueking/chat-x';
+
+  const inputValue = ref('');
+  const citeContent = ref('');
+  const messageStatus = ref(MessageStatus.Complete);
+  const shortcutId = ref('');
+
+  const prompts = ['帮我写一篇关于 {topic} 的文章', '解释一下这段代码'];
+  const resources = [{ id: 'tool1', name: '天气查询', type: 'tool', icon: '' }];
+  const shortcuts: Shortcut[] = [
+    { id: 'translate', name: '翻译' },
+    { id: 'explain', name: '解释' },
+  ];
+
+  const handleSendMessage = async (content, docSchema: TagSchema) => {
+    messageStatus.value = MessageStatus.Streaming;
+    try {
+      await callAI(content, { cite: citeContent.value, shortcut: shortcutId.value });
+    } finally {
+      messageStatus.value = MessageStatus.Complete;
+      citeContent.value = '';
+    }
+  };
+
+  const handleStopSending = async () => {
+    messageStatus.value = MessageStatus.Stop;
+    abortAICall();
+  };
+
+  const handleUpload = async (file: File) => {
+    const formData = new FormData();
+    formData.append('file', file);
+    const res = await fetch('/api/upload', { method: 'POST', body: formData });
+    return res.json(); // { download_url: '...' }
+  };
+</script>
+```
+
+## 关联组件
+
+- [ShortcutBtns](../atomic/shortcut-btns.md) — 底部附件区默认快捷指令列表
+- [ShortcutBtn](../atomic/shortcut-btn.md) — 已选快捷指令单按钮展示
+- [ShortcutRender](./shortcut-render.md) — 含表单的快捷指令表单渲染
+- [ChatContainer](./chat-container.md) — 顶层布局中包裹输入区
+- [CiteContent](../atomic/cite-content.md) — 消息引用区内容展示