@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

package/skills/blueking-chat-x/references/components/file-content.md

@@ -0,0 +1,340 @@
+# FileContent 文件内容
+
+> 能力域：媒体文件 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+渲染文件附件，支持图片预览、上传中/失败态和下载事件。 源码位置：src/components/chat-content/file-content/file-content.vue。
+
+**关联**：image-preview（点击图片缩略图打开全屏预览）、user-message（用户消息只读展示附件列表）
+
+---
+
+# FileContent 文件内容展示
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/file-content/file-content.vue`
+- **能力域**：媒体文件
+- **能力说明**：渲染文件附件，支持图片预览、上传中/失败态和下载事件。
+
+> **能力域**：媒体文件
+
+文件列表展示组件，支持图片缩略图预览、点击图片全屏预览（`ImagePreview`）、文件卡片展示（类型图标 / 文件名 / 文件大小）、上传中/失败态、图片加载失败占位和删除操作。
+
+内部由三个子组件承载单项渲染：
+
+| 子组件             | 源码位置                                                            | 职责                                          |
+| ------------------ | ------------------------------------------------------------------- | --------------------------------------------- |
+| `UploadImageItem`  | `src/components/chat-content/file-content/upload-image-item.vue`  | 图片缩略图、上传中遮罩、失败占位、hover 删除徽标 |
+| `UploadFileItem`   | `src/components/chat-content/file-content/upload-file-item.vue`   | 180px 文件卡片（`FileIcon` + 文件名 + 大小 / 失败文案） |
+| `UploadSpinner`    | `src/components/chat-content/file-content/upload-spinner.vue`     | 16px 白色环形 loading，文件与图片共用         |
+
+## 渲染决策逻辑
+
+先分组、再渲染。设计稿要求**图片始终排在文件前方**，两类各自成行：
+
+```
+splitUploadFiles(files)  // 单次遍历
+├── 图片组（.ai-files-content-row.is-images）
+│     判定依据：mimeType 或 file.file?.type 以 'image/' 开头
+│     src：file.url 优先，否则用本地 File 的 blob URL（按 key 缓存，移除 / 卸载时 revoke）
+│     加载失败或 status=error → 错误占位（粉色背景 + 红色边框 + 灰色图标），且不进入预览列表
+│     status=pending → 半透明遮罩 + 16px 环形 loading，禁止点击预览
+└── 文件组（.ai-files-content-row.is-files）
+      文件卡片：类型图标（FileIcon，按文件名解析扩展名）+ 文件名 + 文件大小
+      status=pending → 半透明遮罩 + 16px 环形 loading
+      status=error → 浅红底 + 红边框，第二行展示「上传失败」
+```
+
+> **是否为图片只看 MIME，不看 `url`。** 解除上传类型限制后，任意文件上传成功都会拿到 `url`，若按 `url` 判断会把 PDF / DOC 渲染成破图。因此 `url` 只决定 `<img src>` 从哪里来，不参与图片判定。
+
+## 基础用法（文件卡片）
+
+MIME 类型非 `image/*` 的文件，渲染为固定宽 180px 的文件卡片（类型图标 + 文件名 + 大小）。类型图标与文件产物侧栏共用 `FileIcon` 的扩展名映射，`pdf` / `py` / `docx` 等各有专属图标，未登记的扩展名回退兜底图标：
+
+```vue
+<template>
+  <FileContent
+    :files="files"
+    @delete-file="handleDeleteFile"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { FileContent, type UploadFile } from '@blueking/chat-x';
+
+  const files = ref<Partial<UploadFile>[]>([
+    { file: new File(['content'], 'report.pdf', { type: 'application/pdf' }) },
+    { file: new File(['content'], 'data.xlsx', { type: 'application/vnd.ms-excel' }) },
+    { file: new File(['readme'], 'README.md', { type: 'text/markdown' }) },
+  ]);
+
+  const handleDeleteFile = (file: Partial<UploadFile>) => {
+    files.value = files.value.filter(f => f !== file);
+  };
+</script>
+```
+
+**渲染效果**（悬停文件卡片，底色加深并在右上角出现删除徽标）
+
+## 图片文件预览
+
+MIME 为 `image/*` 时渲染为图片缩略图（`cursor: zoom-in`）。点击图片可打开全屏预览（内部集成 `ImagePreview` 组件），支持缩放、旋转、下载等操作：
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { type UploadFile } from '@blueking/chat-x';
+
+  const imageFiles = ref<Partial<UploadFile>[]>([
+    {
+      url: 'https://example.com/cat.jpg',
+      filename: 'cat.jpg',
+      mimeType: 'image/jpeg', // 图片判定依据
+      file: new File([''], 'cat.jpg', { type: 'image/jpeg' }),
+    },
+    {
+      url: 'https://example.com/dog.png',
+      filename: 'dog.png',
+      mimeType: 'image/png',
+      file: new File([''], 'dog.png', { type: 'image/png' }),
+    },
+  ]);
+</script>
+```
+
+**渲染效果**
+
+## 图片点击预览
+
+图片模式下点击缩略图会打开全屏预览弹窗。多张图片时支持左右切换。加载失败的图片不会出现在预览列表中：
+
+```vue
+<template>
+  <FileContent :files="imageFiles" />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { FileContent, type UploadFile } from '@blueking/chat-x';
+
+  const imageFiles = ref<Partial<UploadFile>[]>([
+    { url: 'https://example.com/cat.jpg', filename: 'cat.jpg', mimeType: 'image/jpeg' },
+    { url: 'https://example.com/dog.png', filename: 'dog.png', mimeType: 'image/png' },
+  ]);
+</script>
+```
+
+> **预览行为**：组件内部自动维护 `ImagePreview` 实例，无需外部管理预览状态。只有加载成功的图片才会进入预览列表，加载失败的图片被自动过滤。
+
+## 上传中 / 上传失败
+
+`FileContent` 消费每项的 `status`（`UploadStatus`）。尺寸不变：文件卡片仍是 180×48，图片仍是定高 48、宽 48~120。loading 用共享的 `UploadSpinner`（16px 白环），不要用 `AiLoading`。删除徽标始终叠在遮罩之上。
+
+| status    | 文件卡片 | 图片缩略图 |
+| --------- | -------- | ---------- |
+| `pending` | `rgba(0,0,0,0.3)` 遮罩 + spinner | 保留预览图 + `rgba(0,0,0,0.5)` 遮罩 + spinner，点击不打开预览 |
+| `error`   | 背景 `#fff0f0`、边框 `#ea3636`，第二行「上传失败」 | 与加载失败相同的破图占位（18px `ImageErrorIcon`） |
+| `success` / 未设置 | 正常卡片 | 正常缩略图，可预览 |
+
+上传中与上传失败的图片都不会进入 `ImagePreview` 列表。`ChatInput` 在存在 `pending` / `error` 附件时会拦截发送（见 [ChatInput](/components/input/chat-input)）。
+
+## 图片加载失败
+
+`<img>` 触发 `onerror` 时，切换为粉色背景 + 红色边框的错误占位（与 `status=error` 同一套 UI）：
+
+## 混合文件（图片 + 文件）
+
+同一列表可同时包含图片和其他文件，组件内部自动把图片排在前一行、文件排在后一行，各行内部横向排列并按需换行：
+
+```vue
+<script setup lang="ts">
+  const files = [
+    { url: 'https://example.com/photo.jpg', filename: 'photo.jpg', mimeType: 'image/jpeg' },
+    { file: new File(['content'], 'report.pdf', { type: 'application/pdf' }) },
+    { file: new File(['data'], 'data.xlsx', { type: 'application/vnd.ms-excel' }) },
+  ];
+</script>
+```
+
+**渲染效果**
+
+## 只读模式（readonly）
+
+传入 `readonly` 时，隐藏删除按钮，适用于用户消息中展示已发送的文件：
+
+```vue
+<FileContent :files="files" :readonly="true" />
+```
+
+**渲染效果**（悬停无删除按钮）
+
+## 仅有 filename（无 File 对象）
+
+从服务端恢复的历史文件没有 `File` 对象时仍可渲染文件卡片，类型图标从 `filename` 推断。文件大小取 `size` 字段；未下发 `size` 时大小节点不渲染：
+
+```vue
+<script setup lang="ts">
+  const remoteFiles = [
+    // 无 file 对象，未带 size，文件大小不渲染
+    { filename: 'server-report.pdf', mimeType: 'application/pdf' },
+    // 带 size 时正常显示「1.00M」
+    { filename: 'config.json', mimeType: 'application/json', size: 1024 * 1024 },
+  ];
+</script>
+```
+
+**渲染效果**（未带 `size` 的项无大小行）
+
+## 在 ChatInput 中使用
+
+`FileContent` 由 `ChatInput` 内部自动渲染在文件预览区（`slot#files` 的默认内容），通常不需要手动引入。当 `ChatInput` 收到上传文件时，自动更新 `uploadFiles` 并渲染：
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    :on-send-message="handleSendMessage"
+    :on-upload="handleUpload"
+  />
+</template>
+```
+
+若需自定义文件展示，通过 `slot#files` 替换默认 `FileContent`：
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    :on-upload="handleUpload"
+  >
+    <template #files="{ files }">
+      <!-- 自定义文件列表 UI -->
+      <FileContent
+        :files="files"
+        readonly
+      />
+    </template>
+  </ChatInput>
+</template>
+```
+
+## 上传文件预览
+
+具有 `outputId` 且不处于上传中 / 失败态的附件，在 `ChatContainer` 内点击会通过统一的文件产物侧栏预览，使用 `onArtifactClick` 获取预览和下载链接。图片缩略图链接失效时仍可按 `outputId` 重新取链；无 `outputId` 的图片继续使用原有图片预览。
+
+## API
+
+### Props
+
+| 属性名   | 类型                    | 默认值    | 必填 | 说明                                        |
+| -------- | ----------------------- | --------- | ---- | ------------------------------------------- |
+| files    | `Partial<UploadFile>[]` | -         | ✅   | 文件列表                                    |
+| readonly | `boolean`               | `false`   | -    | 只读模式，`true` 时隐藏删除徽标与 hover 态 |
+| variant  | `'input' \| 'message'`  | `'input'` | -    | 展示形态，见下方「展示形态」                |
+
+### 展示形态（variant）
+
+只影响图片缩略图的圆角描边与整体对齐，文件卡片两种形态一致。图片尺寸规则两种形态相同：**定高 48px，宽度按原图比例，并在 48~120px 之间夹取**（竖图不至于过窄，长图不会撑破容器），超出部分由 `object-fit: cover` 裁切。
+
+| variant     | 使用场景           | 图片圆角 / 描边 | 对齐   |
+| ----------- | ------------------ | --------------- | ------ |
+| `'input'`   | 输入框内待发送态   | 8px / `#f0f1f5` | 左对齐 |
+| `'message'` | 用户消息内已发送态 | 4px / `#eaebf0` | 右对齐 |
+
+### Events
+
+| 事件名     | 参数                          | 触发时机           |
+| ---------- | ----------------------------- | ------------------ |
+| deleteFile | `(file: Partial<UploadFile>)` | 点击删除按钮时触发 |
+
+## 渲染模式详解
+
+### 图片模式
+
+| 条件                | 图片 src                                          | 点击行为       |
+| ------------------- | ------------------------------------------------- | -------------- |
+| `file.url` 有值     | `file.url`                                        | 打开全屏预览   |
+| 无 url、有 `File`   | `URL.createObjectURL(file.file)`（按 key 缓存）  | 打开全屏预览   |
+| 图片加载失败        | 错误占位                                          | 不进入预览列表 |
+| `status` 为 pending / error | 遮罩 loading 或错误占位                    | 不进入预览列表 |
+
+blob URL 按附件 key 缓存，同一文件重复渲染不会重复创建；文件被移除或组件卸载时统一 `revokeObjectURL`。
+
+### 文件卡片模式
+
+| 字段     | 取值优先级                                    |
+| -------- | --------------------------------------------- |
+| 文件名   | `file.filename` → `file.file?.name`           |
+| 类型图标 | 由文件名解析扩展名，交给 `FileIcon` 映射      |
+| 文件大小 | `file.file?.size` → `file.size`；都没有则不渲染 |
+
+## 类型定义
+
+```typescript
+import type { UploadFile, BinaryInputContent } from '@blueking/chat-x';
+
+// 上传状态：ChatInput 写入，FileContent 消费以渲染 pending / error
+enum UploadStatus {
+  Pending = 'pending', // 上传中
+  Success = 'success', // 上传成功
+  Error = 'error', // 上传失败
+}
+
+// 上传文件（FileContent 的 files 数组中每一项）
+type UploadFile = BinaryInputContent & {
+  file?: File; // 原始 File 对象，无则文件大小不显示
+  status?: UploadStatus; // 上传状态（pending 遮罩 loading，error 失败样式）
+};
+
+// 二进制内容基础类型
+interface BinaryInputContent {
+  type: 'binary';
+  url?: string; // 文件访问地址，只决定 <img src> 来源，不参与图片判定
+  filename?: string; // 文件名（文件卡片展示 + 类型图标解析）
+  mimeType?: string; // MIME 类型（图片判定依据）
+  size?: number; // 文件字节数，发送时由原始 File 写入
+}
+```
+
+## 工具函数（`src/utils/upload-file.ts`）
+
+组件内的取值与分组逻辑都收敛在这里，`ChatInput`、`UserMessage` 共用同一套判定：
+
+```typescript
+import {
+  getFileIdentity,
+  getUploadFileKey,
+  getUploadFileName,
+  getUploadFileSize,
+  isUploadImageFile,
+  splitUploadFiles,
+} from '@blueking/chat-x';
+
+// File 身份：文件名 + 大小 + 修改时间，用于去重与列表 key
+getFileIdentity(file); // 'report.pdf_2048_1700000000000'
+
+// 附件稳定 key：待发送态用 File 身份（上传成功回填 url 后不变），已发送态退回 url / 文件名
+getUploadFileKey({ file }); // 'report.pdf_2048_1700000000000'
+getUploadFileKey({ url: 'https://x/a.pdf' }); // 'https://x/a.pdf'
+
+// 是否按图片渲染：只看 MIME，有 url 也不例外
+isUploadImageFile({ mimeType: 'application/pdf', url: 'https://x/a.pdf' }); // false
+
+// 文件名 / 字节数取值优先级
+getUploadFileName({ filename: 'remote.pdf', file }); // 'remote.pdf'
+getUploadFileSize({ size: 2048 }); // 2048
+
+// 单次遍历分出图片组与其他文件组（图片在前）
+splitUploadFiles(files); // { imageFiles, otherFiles }
+```
+
+## 使用场景
+
+- **ChatInput 文件预览区**：上传文件后在编辑器上方展示待发送的文件列表（可删除）
+- **用户消息展示**：`UserMessage` 内部以 `readonly` 模式展示已发送的图片和附件
+- **历史消息回放**：服务端返回的文件信息（无 `File` 对象）也能正常渲染文档卡片
+
+## 关联组件
+
+- [ImagePreview](/components/medias/image-preview) — 图片全屏预览
+- [UserMessage](/components/message/user-message) — 用户消息内附件展示

package/skills/blueking-chat-x/references/components/file-icon.md

@@ -0,0 +1,109 @@
+# FileIcon 文件类型图标
+
+> 能力域：辅助能力 ｜ 导入：`import { FileIcon } from '@blueking/chat-x'` ｜ since 1.0.0
+
+按扩展名渲染文件类型图标：内联 svg，尺寸用 1em 跟随外层 font-size； 扩展名解析走 normalizeFileExtension（优先 fileType，缺省回退 fileName，大小写不敏感， 支持 Dockerfile / .gitignore 这类无扩展名或点号开头的文件）；未登记类型返回 unknown 兜底图标。 源码位置：src/components/file-icon/file-icon.vue，图标注册表在 src/icons/file-icons.ts。
+
+**关联**：file-artifact-panel（文件产物列表与预览头使用该组件展示类型图标）、assistant-message（消息内的文件产物卡片使用该组件）
+
+---
+
+# FileIcon 文件类型图标
+
+> **能力域**：辅助能力
+
+`FileIcon` 按文件扩展名渲染对应的类型图标，用于文件列表、附件卡片、产物预览头等需要「一眼看出这是什么文件」的场景。图标以内联 svg 形式打进包内，不产生额外网络请求，也不需要消费方配置静态资源路径。
+
+## 源码事实
+
+- **源码位置**：`src/components/file-icon/file-icon.vue`
+- **图标注册表**：`src/icons/file-icons.ts`（导出 `getFileIconSvg` / `UNKNOWN_FILE_ICON_SVG`）
+- **扩展名解析**：`src/utils/file-type.ts` 的 `normalizeFileExtension`
+
+## 核心能力
+
+- **扩展名驱动**：优先取 `fileType`，缺省时回退 `fileName` 推断；大小写不敏感
+- **特殊文件名**：`Dockerfile` / `Makefile` 这类无扩展名文件，以及 `.gitignore` / `.editorconfig` 这类点号开头的文件都能正确命中
+- **多扩展名共用图标**：如 `xlsx` / `xls` / `csv` / `tsv` 共用表格图标，`tsx` / `jsx` 共用 React 图标
+- **兜底不报错**：未登记的扩展名返回 `unknown` 图标，后台新增文件类型时前端不会缺图
+- **尺寸自适应**：内部 svg 固定为 `1em`，直接用外层 `font-size` 控制大小
+
+## 基础用法
+
+```vue
+<template>
+  <FileIcon file-type="pdf" />
+</template>
+
+<script setup lang="ts">
+  import { FileIcon } from '@blueking/chat-x';
+</script>
+```
+
+**渲染效果**
+
+## 从文件名推断
+
+后台未下发 `type` 时传 `fileName` 即可，组件会取最后一段扩展名：
+
+```vue
+<template>
+  <!-- 取 xlsx -->
+  <FileIcon file-name="季度报告.final.xlsx" />
+  <!-- 取 gitignore -->
+  <FileIcon file-name=".gitignore" />
+</template>
+```
+
+两者同时传入时以 `fileType` 优先。
+
+## 控制尺寸
+
+图标宽高为 `1em`，用外层 `font-size` 控制即可，无需改 svg：
+
+```vue
+<template>
+  <span style="font-size: 16px"><FileIcon file-type="py" /></span>
+  <span style="font-size: 32px"><FileIcon file-type="py" /></span>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型     | 必填 | 默认值      | 说明                                                     |
+| -------- | -------- | ---- | ----------- | -------------------------------------------------------- |
+| fileType | `string` | 否   | `undefined` | 文件类型：扩展名（如 `pdf` / `py`）或无扩展名文件名（如 `Dockerfile`） |
+| fileName | `string` | 否   | `undefined` | 文件名，`fileType` 缺省时用于推断扩展名                    |
+
+两者都不传时渲染兜底图标。
+
+### Emits / Slots / Expose
+
+- 无。
+
+## 图标覆盖范围
+
+| 图标 | 覆盖扩展名 |
+| ---- | ---------- |
+| 文档类 | `pptx` / `docx` / `pdf` / `txt` / `rst` / `md` / `markdown` / `tex` |
+| 表格类 | `xlsx` / `xlsm` / `xls` / `csv` / `tsv` |
+| 前端 | `html` / `htm` / `css` / `scss` / `less` / `js` / `mjs` / `cjs` / `ts` / `tsx` / `jsx` / `vue` / `xml` |
+| 后端 / 系统 | `py` / `go` / `rs` / `rb` / `java` / `kt` / `swift` / `c` / `h` / `cpp` / `hpp` / `cs` / `php` / `lua` / `r` / `scala` / `dart` / `sql` / `sh` / `bash` / `zsh` / `ps1` |
+| 配置 | `json` / `jsonc` / `yaml` / `yml` / `toml` / `ini` / `cfg` / `conf` / `env` / `editorconfig` / `Makefile` |
+| 工具链 | `Dockerfile` / `dockerignore` / `gitignore` |
+| 图片 | `png` / `jpg` / `jpeg` / `svg` |
+| 兜底 | 以上之外的所有类型 |
+
+新增类型时在 `src/icons/file-icons.ts` 的 `FILE_ICON_GROUPS` 里补一行即可；对应 svg 需先放进 `src/svgs/` 并按需 `?raw` 引入（只引实际用到的，避免把整个图标库打进产物）。
+
+## 使用建议
+
+- 图标颜色由 svg 自带，不继承 `currentColor`，不要试图用 `color` 覆盖
+- 需要与文件名同行展示时，给父容器设 `display: flex` + `gap`，组件本身已是 `inline-flex` 且 `flex-shrink: 0`
+
+## 关联组件
+
+- [FileArtifactPanel](../message/file-artifact-panel.md) — 文件产物列表与预览头使用该组件。
+- [AssistantMessage](../message/assistant-message.md) — 消息内文件产物卡片的图标来源。

package/skills/blueking-chat-x/references/components/file-upload-btn.md

@@ -0,0 +1,162 @@
+# FileUploadBtn 文件上传按钮
+
+> 能力域：输入交互 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+文件选择按钮，封装 input[type=file] 并输出选择事件。 源码位置：src/components/ai-buttons/file-upload-btn/file-upload-btn.vue。
+
+**关联**：add-menu-btn（ChatInput 内部已改用 + 号聚合菜单承载上传入口）、chat-input（输入区附件上传按钮常见挂载位置）、file-content（选中文件常以列表形式展示待发送内容）
+
+---
+
+# FileUploadBtn 文件上传按钮
+## 源码事实
+
+- **源码位置**：`src/components/ai-buttons/file-upload-btn/file-upload-btn.vue`
+- **能力域**：输入交互
+- **能力说明**：文件选择按钮，封装 input[type=file] 并输出选择事件。
+
+> **能力域**：输入交互
+
+::: warning ChatInput 已不再使用本按钮
+输入区重构后，`ChatInput` 的上传入口改为左下角 [AddMenuBtn](/components/input/add-menu-btn) 聚合菜单里的「文件」项（内部走自持的隐藏 `input[type=file]`）。本组件仍保留在源码中并可用于自建输入区，但**不会**出现在 `ChatInput` 的默认布局里，也**未从包入口导出**——文档站示例经相对路径引入。
+:::
+
+文件上传触发按钮，点击后弹出系统文件选择框。内部包含隐藏的 `<input type="file">` 与可见的图标按钮；**不限制文件类型**，在按钮层只对**单文件**做大小与空文件过滤，**已选文件个数上限**由上层统一校验并提示，避免按钮与输入区各弹一条错误提示。
+
+## 组件结构
+
+```
+.ai-file-upload-btn（display: flex，align-items: center）
+├── input[type="file"]（.file-upload-btn-input，display: none，multiple，:accept）
+│     accept 缺省时不下发该属性，系统选择框不过滤任何类型
+│     触发后走 handleFileInputChange → 校验 → emit upload → target.value = ''
+└── span.ai-shortcut-btn.file-upload-btn-icon（热区 32×32px / 圆角 8px；图标字号跟随 --ai-icon-size-sm：small=16px、normal=18px；color: #979ba5；hover: #f0f1f5）
+      v-tippy: "上传文件，最多支持 {count} 个，单个最大 {size}MB"
+        （{count} / {size} 由 MAX_UPLOAD_FILES 与 MAX_UPLOAD_FILE_SIZE 运行时填充，theme: ai-chat-box，offset: [0, 16]，可通过 tippyOptions 扩展）
+      @click → fileInputRef.click()
+      └── <slot> 默认：FileUploadIcon
+```
+
+## 文件校验逻辑
+
+```
+用户选择文件
+  │
+  ├─ 遍历所选文件：size > 0 且 size < MAX_UPLOAD_FILE_SIZE（45MB）→ 加入 toEmit
+  │       size 为 0 或 ≥ 上限 → sizeRejected += 1
+  │
+  ├─ sizeRejected > 0 → bkui-vue Message.error（formatUploadNotAddedMessage，说明可能超大或超出个数等）
+  │
+  ├─ toEmit.length > 0 → emit('upload', toEmit)
+  │
+  └─ target.value = ''（重置 input，允许再次选择同一文件）
+```
+
+**关键边界行为**：
+
+| 场景                                                         | 结果                                                                 |
+| ------------------------------------------------------------ | -------------------------------------------------------------------- |
+| 一次多选超过上层允许个数                                     | 由**上层**（如输入区）toast 并丢弃 / 不计入，不在本按钮内按个数提前拦截 |
+| 部分文件因空文件或单文件超大被过滤                           | 弹出错误 toast；若仍有合法文件，**仍触发** `upload`（payload 为合法子集） |
+| 全部被过滤（均为空或超大）                                   | 仅 toast，**不触发** `upload`                                        |
+| `file.size === 0`                                          | 计入未添加提示，不进入 `upload` payload                              |
+| `file.size >= MAX_UPLOAD_FILE_SIZE`（与全局常量一致，45MB） | 计入未添加提示，不进入 `upload` payload（比较为严格 `<`）           |
+| 选择后取消                                                   | `files.length === 0`，不触发 `upload`                                |
+
+> `multiple` prop 声明存在但当前模板中 `input` 的 `multiple` 属性为**硬编码**（非 `:multiple="multiple"` 绑定），始终允许多选，该 prop 暂时无实际效果。
+
+> **文件类型不做限制**：组件不再默认 `accept="image/*"`，任意类型文件都可选择。若业务需要收窄，显式传入 `accept`。个数上限由上层控制（`MAX_UPLOAD_FILES`），详见 [ChatInput 文件上传](/components/input/chat-input#file-upload)。
+
+## 基础用法
+
+```vue
+<template>
+  <FileUploadBtn @upload="handleUpload" />
+</template>
+
+<script setup lang="ts">
+  const handleUpload = (files: File[]) => {
+    console.log(
+      '选中文件:',
+      files.map(f => `${f.name}(${f.size}B)`),
+    );
+  };
+</script>
+```
+
+## 限制文件类型
+
+默认**不限制**文件类型。需要收窄时通过 `accept` 属性控制系统文件选择框的过滤条件，遵循 `<input type="file">` 的 `accept` 规范：
+
+```vue
+<template>
+  <!-- 不限制类型（默认，不下发 accept） -->
+  <FileUploadBtn @upload="handleUpload" />
+
+  <!-- 仅图片 -->
+  <FileUploadBtn
+    accept="image/*"
+    @upload="handleUpload"
+  />
+
+  <!-- 文档类型 -->
+  <FileUploadBtn
+    accept=".pdf,.doc,.docx,.xlsx,.pptx"
+    @upload="handleUpload"
+  />
+</template>
+```
+
+> `accept` 仅影响文件选择框的过滤 UI，不做服务端验证，请在 `upload` 回调中自行校验 MIME 类型。
+
+## 自定义图标
+
+通过默认插槽替换上传图标：
+
+```vue
+<template>
+  <FileUploadBtn @upload="handleUpload">
+    <span style="font-size: 16px; line-height: 1;">📎</span>
+  </FileUploadBtn>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型           | 默认值 | 说明                                                                       |
+| ------------ | -------------- | ------ | -------------------------------------------------------------------------- |
+| accept       | `string`       | —      | 文件选择框过滤类型，遵循 `<input accept>` 规范；缺省时不下发，不限制类型 |
+| multiple     | `boolean`      | `true` | 声明属性（当前版本未实际绑定到 input，始终多选）                           |
+| tippyOptions | `AITippyProps` | —      | 扩展 tooltip 配置，会与内置配置合并                                        |
+
+### Events
+
+| 事件名 | 参数              | 说明                                                                                      |
+| ------ | ----------------- | ----------------------------------------------------------------------------------------- |
+| upload | `(files: File[])` | 当存在至少一个合法文件时触发；`files` 为过滤掉空文件与单文件超大（`size >= MAX_UPLOAD_FILE_SIZE`，45MB）后的数组；个数截断不在此组件内完成 |
+
+### Slots
+
+| 插槽名  | 说明                                            |
+| ------- | ----------------------------------------------- |
+| default | 自定义按钮图标内容，默认为内置 `FileUploadIcon` |
+
+## 使用场景
+
+仅在**自建输入区**时使用。若使用 `ChatInput`，上传能力由 `supportUpload`（默认 `true`）开启，入口是 + 号菜单里的「文件」项、拖拽与粘贴，无需再挂本按钮。
+
+## 类型定义
+
+```typescript
+import type { TippyOptions } from 'vue-tippy';
+
+type AITippyProps = Partial<Pick<TippyOptions, 'appendTo' | 'placement' | 'zIndex'>>;
+```
+
+## 关联组件
+
+- [AddMenuBtn](/components/input/add-menu-btn) — `ChatInput` 现行的上传 / 资源入口
+- [ChatInput](/components/input/chat-input) — 上传能力与校验规则
+- [FileContent](/components/medias/file-content) — 选中文件列表展示