多模态输入输出与文件预览
多模态输入输出与文件预览
概述
Claw 支持丰富的多模态交互：用户可以发送图片、文档、音频等多种类型的内容给 Agent；Agent 的回复中可以包含代码、文档、图表等多种格式的输出，均支持内联预览和全屏查看。
多模态输入
支持的输入类型
| 内容块类型 | 说明 | 示例 |
|---|---|---|
text |
纯文本 | 用户消息、代码片段 |
image |
图片 | PNG、JPEG、GIF、WebP（base64 编码） |
document |
文档 | PDF 文档（base64 编码） |
audio |
音频 | 音频文件 |
file_ref |
文件引用 | 本地文件路径引用 |
上传方式
- 拖拽上传 — 将文件直接拖到输入区
- 点击上传 — 点击输入区的附件按钮选择文件
- 粘贴 — 从剪贴板粘贴图片
模型格式适配
系统根据当前使用的 LLM 供应商自动转换输入格式：
| 供应商 | 图片 | 文档 | 音频 |
|---|---|---|---|
| Anthropic | 原生 base64 image 块 | 原生 base64 document 块 | 不支持 |
| OpenAI | image_url（data URI） | 降级为文本描述 | 原生 audio 块 |
| DeepSeek | 不支持 | 不支持 | 不支持 |
系统通过 resolveCapabilities 函数自动检测当前模型的多模态能力（vision / document / audio），不支持的类型会提示用户或降级处理。
多模态输出与预览
9 种预览类型
Agent 输出的文件会被自动识别类型并渲染为对应的预览组件：
| 文件类型 | 预览组件 | 功能按钮 |
|---|---|---|
| PdfPreviewWindow | 缩放（放大/缩小/适合宽度）、翻页、页码显示 | |
| PPT | PptPreviewWindow | 幻灯片导航（上一页/下一页）、缩放 |
| Excel / Word | OfficePreviewWindow | 缩放、翻页 |
| 代码 | CodePreviewWindow | 语法高亮（多语言）、复制到剪贴板 |
| Markdown | MarkdownPreviewWindow | Markdown 渲染预览 |
| HTML | HtmlPreviewWindow | 嵌入式 iframe 渲染 |
| 图片 | MediaPreviewWindow | 缩放、拖拽平移 |
| 视频 | MediaPreviewWindow | 播放/暂停、进度条、音量控制 |
| 音频 | MediaPreviewWindow | 播放/暂停、进度条 |
内联预览卡片
Agent 输出的文件首先以**内联预览卡片（InlinePreviewCard）**的形式出现在对话流中：
| 元素 | 说明 |
|---|---|
| 标题栏 | 文件名、类型徽章、操作按钮 |
| 缩略内容 | 文件内容预览（折叠状态，底部渐变 + "显示更多"提示） |
| 悬停效果 | 高亮边框 + 阴影提升 |
操作按钮（图标 + 工具提示）：
| 按钮 | 功能 |
|---|---|
| 展开 | 全屏预览窗口 |
| 复制 | 复制内容到剪贴板 |
| 文件管理器 | 在系统文件管理器中显示（仅 APP） |
| 外部打开 | 用默认应用打开（本地文件）或在浏览器打开（URL） |
全屏预览窗口
点击"展开"按钮进入全屏预览窗口：
预览工具栏（PreviewToolbar）：
- 缩放控制：放大 / 缩小 / 适合宽度
- 页面导航：上一页 / 下一页（多页文档）
- 页码状态：当前页 / 总页数
快捷键：
| 快捷键 | 功能 |
|---|---|
+ 或 = |
放大 |
- |
缩小 |
0 |
重置缩放 |
Esc |
关闭预览窗口 |
预览布局模式
| 模式 | 端 | 说明 |
|---|---|---|
| Overlay（浮层） | APP 端默认 | 固定定位的浮层窗口 |
| Docked（停靠） | Web 端 | 嵌入 ClawPage 右侧面板 |
Web 与 APP 能力共享
多模态预览的核心组件在 claw-shared 层实现，Web 和 APP 共享同一套代码：
DocumentPreviewModal— 预览窗口容器InlinePreviewCard— 内联预览卡片PreviewToolbar— 预览工具栏previewUtils.ts— 文件类型识别与加载工具
两端通过 FileAccess 接口抽象文件读取方式：
- APP 端：通过 Tauri 本地文件 API 读取
- Web 端：通过 HTTP URL 或 data URL 加载
操作指南
如何发送图片/文档给 Agent
- 拖拽上传：将文件从桌面或文件管理器直接拖到 Claw 输入区
- 点击上传：点击输入区左侧的 📎 附件按钮，选择文件
- 粘贴图片：复制图片后在输入区 Ctrl+V / Cmd+V 粘贴
- 附件出现在输入区上方的预览栏中
- 输入文字描述你想让 Agent 做什么（如"分析这张图片"），按 Enter 发送
文件大小限制：Read File 工具支持最大 5MB 的文件。更大的文件建议先上传到云存储再提供链接。
如何使用文件预览
- 当 Agent 输出包含文件时，对话流中会出现内联预览卡片
- 悬停卡片查看更多信息
- 点击 展开 按钮进入全屏预览
- 在全屏预览中使用工具栏操作（缩放、翻页等）
- 按 Esc 或点击关闭按钮退出预览
常见问题
为什么图片发送后 Agent 没有分析？
- 当前模型可能不支持 vision 能力。检查模型配置中的模型是否标记了 vision 支持。DeepSeek 系列模型不支持图片输入。
- 建议切换到 Claude Sonnet 4 或 GPT-4o。
为什么 PDF 发送后只返回"不支持"？
- document 能力目前仅 Anthropic 系列模型（Claude）原生支持。使用 OpenAI 模型时，PDF 会降级处理。
- 替代方案：让 Agent 使用 Read File 工具读取 PDF 文件路径。
预览窗口中文件显示异常
- 确认文件格式正确（如 .xlsx 文件不能用 .csv 后缀）
- 超大文件可能加载缓慢，请等待加载完成
- 部分特殊格式的 Office 文件可能需要在外部应用中打开