@blueking/chat-x 0.0.50 → 0.0.51-beta.2

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

@@ -0,0 +1,289 @@
+# FileArtifactPanel 文件产物预览
+
+> 能力域：消息系统 ｜ 导入：`import { FileArtifactPanel } from '@blueking/chat-x'` ｜ since 0.0.20
+
+汇总当前会话所有 AssistantMessage 的 artifacts（按 outputId 去重），支持关键词搜索、列表选中与下载； 预览区委托 ArtifactPreviewHost：由 resolveFileKind 把扩展名归入 code / markdown / html / text / image / binary 六类， 前四类走 text_from_download 拉正文（code 交给 highlight.js 高亮），image / binary 走 preview_url； download_url / preview_url 经 onArtifactClick 每次异步获取（无 URL 缓存，并发去重）； 预览重载键为 outputId:type；重试再次调用 load() 重新取链。 源码位置：src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue。
+
+**关联**：assistant-message（文件产物来源于 AssistantMessage.property.artifacts）、chat-container（面板挂载在侧栏「文件产物」Tab（固定、不可关闭），并通过 onArtifactClick 异步取链）、execution-summary（同为 ChatContainer 侧栏 Tab 面板，交互形态一致）、message-loading（ArtifactPreviewHost 取链 / 拉取正文过程使用 MessageLoading）
+
+---
+
+# FileArtifactPanel 文件产物预览
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue`
+- **能力域**：消息系统
+- **能力说明**：汇总当前会话全部文件产物；左侧列表搜索与选中，右侧预览委托内部 `ArtifactPreviewHost`。
+
+> **导出说明**：内部侧栏面板组件，**通常不直接使用**；由 `ChatContainer` 在「文件产物」Tab 内自动挂载。预览加载与渲染为同目录下 `artifact-preview/` 内部实现，不单独导出。
+
+点击 AI 回复中的[文件卡片](/components/message/assistant-message)后，`ChatContainer` 侧栏会弹出固定的「文件产物」Tab，聚合展示当前会话**所有** `AssistantMessage` 的文件产物（按 `outputId` 去重），并命中被点击的文件进行预览。
+
+面板左侧为可搜索的文件列表，右侧为预览区。通常不需要直接使用，由 `ChatContainer` 在侧栏内自动渲染。
+
+## 核心能力
+
+- **会话级聚合**：拍平当前会话所有 `AssistantMessage.property.artifacts`，以 `outputId` 去重后统一在一个列表内展示
+- **唯一命中**：以 `outputId` 作为会话内唯一键（同 `outputId` 视为同一文件）；文件名可能重复，不可作唯一键
+- **关键词搜索**：按文件名实时过滤列表
+- **整块空态**：`artifacts` 为空时不渲染列表与预览区，整块展示 bkui `Exception`「暂无数据」（Tab 常驻，无数据也可正常打开侧栏）
+- **异步取链**：`AIFileInfo` 本身不含 `url` / `previewUrl`，通过 `ChatContainer` 的 `onArtifactClick` 按 `outputId` 获取 `download_url` / `preview_url`（TTL 8 分钟缓存；预览重试会 `force` 刷新）
+- **职责拆分**：
+  - **面板本身**：列表、搜索、预览头（文件名 / 图标 / 下载）
+  - **`ArtifactPreviewHost`**：按策略加载正文或预览 URL，分派到对应 renderer；展示 loading / empty / error（含重试）
+- **未传 `onArtifactClick`**：下载按钮隐藏，预览区展示无数据
+
+## 基础用法
+
+面板**未从包入口导出**，业务侧请走下方「业务接入」；下列示例仅用于文档站 / 本地调试（与 `ExecutionSummary` 文档站写法一致：相对路径引入 + 自行挂 Provider）。
+
+```vue
+<template>
+  <div style="height: 480px; border: 1px solid #dcdee5; border-radius: 8px; overflow: hidden;">
+    <FileArtifactPanel
+      :active-id="activeArtifactId"
+      :artifacts="sessionArtifacts"
+      @select="handleSelect"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { shallowRef } from 'vue'
+  import { useArtifactPreviewProvider } from '@blueking/chat-x'
+  import type { AIFileInfo, SessionArtifact } from '@blueking/chat-x'
+  // 内部组件：仅文档 / 调试；业务请用 ChatContainer 自动挂载
+  import FileArtifactPanel from './message-artifacts/file-artifact-panel.vue'
+
+  const sessionArtifacts: SessionArtifact[] = [
+    { name: '周报.html', outputId: 'a-html', size: 10240, type: 'html' },
+    { name: '说明.md', outputId: 'a-md', size: 8192, type: 'md' },
+    { name: '纪要.txt', outputId: 'a-txt', size: 4096, type: 'txt' },
+    { name: '配置.json', outputId: 'a-json', size: 2048, type: 'json' },
+    { name: '立项.pdf', outputId: 'a-pdf', size: 204800, type: 'pdf' },
+  ]
+
+  useArtifactPreviewProvider({
+    getOnArtifactClick: () => async file => {
+      // 文本类返回可 fetch 的 download_url；iframe 类返回 preview_url
+      const res = await api.getArtifactUrls(file.outputId)
+      return { download_url: res.download_url, preview_url: res.preview_url }
+    },
+    onOpen: () => {},
+  })
+
+  const activeArtifactId = shallowRef(sessionArtifacts[0].outputId)
+  const handleSelect = (id: string) => {
+    activeArtifactId.value = id
+  }
+</script>
+```
+
+**渲染效果**（点击左侧列表切换类型；文本类直渲染，PDF 走 iframe。Mock 取链约 600ms）
+
+## 业务接入（ChatContainer）
+
+日常用法是给容器传 `messages`（含 `property.artifacts`）与 `onArtifactClick`，点击文件卡片即可打开侧栏面板：
+
+```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[],
+      },
+    },
+  ])
+
+  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>
+```
+
+## 触发链路
+
+```
+ArtifactFileCard（点击文件卡片）
+  └─ useArtifactPreviewConsumer().openPreview({ file })
+       └─ useArtifactPreviewProvider（ChatContainer 内）
+            ├─ 记录命中文件 activeArtifactId = file.outputId
+            └─ onOpen → addCustomTab('file-artifact') 展开并选中侧栏 Tab
+                 └─ FileArtifactPanel
+                      ├─ 列表 @select → setActiveArtifactId(outputId)
+                      ├─ 下载 → resolveArtifactUrls + triggerArtifactDownload
+                      └─ ArtifactPreviewHost
+                           ├─ useArtifactPreviewLoader（策略 + fetch / 取链，防竞态）
+                           └─ HtmlPreview | MarkdownPreview | TxtPreview | UrlIframePreview
+
+容器初始化
+  └─ ensureCustomTab('file-artifact') 常驻挂上（不展开侧栏）；因 order:-1 排在首位，
+     未主动切换过 Tab 时会成为默认选中面板；无产物时由面板展示整块空态
+```
+
+- 文件卡片通过 `useArtifactPreviewConsumer` 注入预览上下文，无 Provider 时卡片不可点击（兜底 `undefined`）
+- `ChatContainer` 通过 `useArtifactPreviewProvider` 提供上下文，并把「打开侧栏 Tab」这一副作用以 `onOpen` 注入，保持 composable 职责单一
+- 侧栏「文件产物」Tab 固定不可关闭，`order: -1` 排在「执行情况」之前；**常驻不随产物有无增删**，无产物时由面板展示整块空态
+
+## 唯一键规则
+
+会话内以 **`outputId`** 作为文件产物唯一键：
+
+- 同一 `outputId` 在多条消息中出现时，聚合列表去重并保留最后一次出现的文件信息
+- `activeId`、列表 `:key`、`select` 事件参数均使用 `outputId`
+- 文件名可能重复，**不可**作为唯一键
+
+## 预览机制
+
+预览分两步：先由 `resolveFileKind(type, name)`（`src/utils/file-type.ts`）把扩展名归入六个**分类**，再由 `getArtifactPreviewStrategy` 查表得到 **加载方式** 与 **渲染器**。面板与 Host 都不写死具体扩展名分支，后台新增文件类型时只需在分类表里补一行。
+
+| 分类 | 覆盖扩展名 | load | 取链字段 | renderer |
+| ---- | ---------- | ---- | -------- | -------- |
+| `code` | `py` `js` `mjs` `cjs` `ts` `tsx` `jsx` `vue` `go` `rs` `rb` `java` `kt` `swift` `c` `h` `cpp` `hpp` `cs` `php` `lua` `r` `scala` `dart` `sh` `bash` `zsh` `ps1` `sql` `css` `scss` `less` `json` `jsonc` `yaml` `yml` `toml` `ini` `cfg` `conf` `env` `xml` `tex` `Dockerfile` `Makefile` `gitignore` `dockerignore` `editorconfig` | `text_from_download` | `download_url` → `fetch` 正文 | `CodePreview`（highlight.js 高亮） |
+| `markdown` | `md` `markdown` | `text_from_download` | 同上 | `MarkdownPreview`（`MarkdownContent`） |
+| `html` | `html` `htm` | `text_from_download` | 同上 | `HtmlPreview`（`<iframe srcdoc>`） |
+| `text` | `txt` `rst` | `text_from_download` | 同上 | `TxtPreview`（`<pre>`） |
+| `image` | `png` `jpg` `jpeg` `svg` | `preview_url` | `preview_url` | `ImagePreview`（`<img>`，`object-fit: contain`） |
+| `binary` | `pdf` `docx` `xlsx` `xlsm` `xls` `pptx` `csv` `tsv`，以及**所有未登记的扩展名** | `preview_url` | `preview_url` | `UrlIframePreview`（`<iframe src>`，一般为后台转好的 PDF） |
+
+关于类型解析：
+
+- `AIFileInfo.type` 为**扩展名字符串**（如 `'pdf'` / `'py'`）或无扩展名的文件名（如 `'Dockerfile'`），大小写不敏感
+- `type` 缺省时回退 `name` 推断；`报告.final.xlsx` 取 `xlsx`，`.gitignore` 取 `gitignore`
+- `md` 为后台扩展名别名，与 `markdown` 等价，共用 Markdown 直渲染
+- 未登记的扩展名一律落入 `binary` 走后台预览，前端不会因为新类型报错
+
+`CodePreview` 的语言由扩展名映射到 highlight.js（`vue → xml`、`tsx → typescript`、`env / cfg / conf → ini` 等，其余交给 hljs 自身别名表，识别不了则按 `plaintext` 转义输出）。单文件超过 300KB 时跳过高亮直接转义，避免同步解析阻塞主线程。
+
+### 加载态
+
+| status | 表现 |
+| ------ | ---- |
+| `loading` | 预览区 [MessageLoading](/components/helper/message-loading) |
+| `ready` | 对应 renderer 渲染 |
+| `empty` | 「暂无可预览的文件」（无文件 / 未传 `onArtifactClick` / 缺所需 URL） |
+| `error` | 「预览加载失败」+ 重试按钮 |
+
+### 重载与取链约定
+
+- **重载键**：`ArtifactPreviewHost` 以 `` `${outputId}:${type}` `` 监听文件变化；`outputId` 或 `type` 任一变化会重新 `load()`，仅改文件名等其它字段不会
+- **取链**：`resolveArtifactUrls(file)` 每次重新调用 `onArtifactClick`；同文件进行中的请求会复用（并发去重）
+- **重试**：错误态点击重试再次走 `load()`，重新取链并加载
+- **竞态**：切换文件时 `useArtifactPreviewLoader` 用 `loadSeq` + `AbortController` 中断上一次 `fetch`，避免过期结果覆盖最新内容
+
+下载图标仍由面板用 bkui `Loading` spin 单独表达。
+
+## 内部结构（不导出）
+
+```
+message-artifacts/
+├── file-artifact-panel.vue          # 列表 + 下载头 + 挂载 Host
+└── artifact-preview/
+    ├── artifact-preview-host.vue    # 状态机 UI + 分派 renderer
+    ├── preview-strategy.ts          # getArtifactPreviewStrategy（分类 → 策略查表）
+    ├── use-artifact-preview-loader.ts
+    └── renderers/
+        ├── code-preview.vue
+        ├── html-preview.vue
+        ├── image-preview.vue
+        ├── markdown-preview.vue
+        ├── txt-preview.vue
+        └── url-iframe-preview.vue
+```
+
+分类表与扩展名归一化在 `src/utils/file-type.ts`（导出 `AIFileKind` / `resolveFileKind` / `normalizeFileExtension`），与[文件图标](/components/helper/file-icon)共用同一份解析入口。
+
+## API
+
+### Props
+
+| 属性名    | 类型                | 必填 | 说明                                   |
+| --------- | ------------------- | ---- | -------------------------------------- |
+| activeId  | `string`            | ✓    | 当前命中的文件 `outputId`              |
+| artifacts | `SessionArtifact[]` | ✓    | 当前会话全部文件产物（已按 `outputId` 去重） |
+
+### Events
+
+| 事件名 | 参数              | 说明                       |
+| ------ | ----------------- | -------------------------- |
+| select | `(id: string)`    | 列表内切换选中文件，参数为文件 `outputId` |
+
+### Slots / Expose
+
+无。
+
+## 类型定义
+
+```typescript
+import type { AIFileInfo, SessionArtifact } from '@blueking/chat-x';
+
+// 会话级文件产物：拍平去重后即为 AIFileInfo
+type SessionArtifact = AIFileInfo;
+
+type AIFileInfo = {
+  name: string;
+  outputId: string;
+  size: number;
+  /** 扩展名（如 'pdf' / 'py'）或无扩展名文件名（如 'Dockerfile'），大小写不敏感 */
+  type: string;
+};
+```
+
+> **破坏性变更**：原 `AIFileType` 枚举已移除，`AIFileInfo.type` 改为 `string`。此前写 `type: AIFileType.Pdf` 的代码改为 `type: 'pdf'` 即可；枚举成员的值与新字符串一一对应，运行时数据无需迁移。
+
+## 关联 Composable
+
+预览**命中与取链**由 [useArtifactPreview](/composables/use-artifact-preview) 提供（Provider / Consumer + `ARTIFACT_PREVIEW_TOKEN`）。**正文加载与渲染**由内部 `useArtifactPreviewLoader` + `ArtifactPreviewHost` 完成，不在该 composable 内。
+
+## 关联组件
+
+- [AssistantMessage](/components/message/assistant-message) — 文件产物来源（`property.artifacts`）
+- [ChatContainer](/components/setup/chat-container) — 侧栏「文件产物」Tab 挂载场景，提供 `onArtifactClick`
+- [MessageLoading](/components/helper/message-loading) — Host 预览区异步加载态
+- [ExecutionSummary](/components/agent/execution-summary) — 同为侧栏 Tab 面板

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

@@ -0,0 +1,319 @@
+# FileContent 文件内容
+
+> 能力域：媒体文件 ｜ 导入：`import { FileContent } from '@blueking/chat-x'` ｜ 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` + 文件名 + 大小） |
+
+## 渲染决策逻辑
+
+先分组、再渲染。设计稿要求**图片始终排在文件前方**，两类各自成行：
+
+```
+splitUploadFiles(files)  // 单次遍历
+├── 图片组（.ai-files-content-row.is-images）
+│     判定依据：mimeType 或 file.file?.type 以 'image/' 开头
+│     src：file.url 优先，否则用本地 File 的 blob URL（按 key 缓存，移除 / 卸载时 revoke）
+│     加载失败 → 错误占位（粉色背景 + 红色边框 + 灰色图标），且不进入预览列表
+└── 文件组（.ai-files-content-row.is-files）
+      文件卡片：类型图标（FileIcon，按文件名解析扩展名）+ 文件名 + 文件大小
+```
+
+> **是否为图片只看 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` 实例，无需外部管理预览状态。只有加载成功的图片才会进入预览列表，加载失败的图片被自动过滤。
+
+## 图片加载失败
+
+`<img>` 触发 `onerror` 时，切换为粉色背景 + 红色边框的错误占位：
+
+## 混合文件（图片 + 文件）
+
+同一列表可同时包含图片和其他文件，组件内部自动把图片排在前一行、文件排在后一行，各行内部横向排列并按需换行：
+
+```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>
+```
+
+## 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 缓存）  | 打开全屏预览   |
+| 图片加载失败        | 错误占位                                          | 不进入预览列表 |
+
+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 不使用此字段）
+enum UploadStatus {
+  Pending = 'pending', // 上传中
+  Success = 'success', // 上传成功
+  Error = 'error', // 上传失败
+}
+
+// 上传文件（FileContent 的 files 数组中每一项）
+type UploadFile = BinaryInputContent & {
+  file?: File; // 原始 File 对象，无则文件大小不显示
+  status?: UploadStatus; // 上传状态（ChatInput 使用，FileContent 不消费）
+};
+
+// 二进制内容基础类型
+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) — 用户消息内附件展示