文件预览
了解知识库中各类文件的预览功能
文件预览
Knodo 知识库支持多种文件格式的在线预览。本文档介绍各类文件的预览功能和使用方法。
预览功能概述
在知识库中点击文件即可预览内容，无需下载：
-
支持多种文件格式
-
快速加载
-
响应式显示
主空间与执行环境
文件树、聊天消息和 Markdown 中的文件预览共用同一套文件类型、大小限制、Range 和浏览器隔离策略。打开执行环境文件时，请求只额外携带当前执行环境绑定 ID；服务端 据此选择对应的文件适配器和允许根目录，主空间与执行环境中同名文件互不混淆。
执行环境支持主空间已有的图片、PDF、Office、XMind、HTML、文本、音视频等预览类型。 浏览器无法直接解码的 TIFF、HEIC/HEIF 图片会显示为不支持在线预览，避免破图或持续加载。
内嵌内容预览按文件类型执行大小上限，HTML/HTM/JS 为 5 MiB。超过该上限的 HTML 可通过 “在新标签页打开”查看，HTML/HTM 和引用的 JS 文件流式加载不设固定大小上限；CSS、图片等 其他相对资源仍执行各自类型的预览上限。新标签预览保留原有浏览器隔离策略。
流式预览支持单段 HTTP Range 请求。文件内容会在同一受限读取流内输出，文件缩短或 读取异常时会拒绝返回不完整响应。
自动刷新
当 Agent、Sandbox 命令、后台任务或外部进程修改工作空间文件后，已打开的文件预览会自动刷新：
-
当前文件发生变更时，文本、Markdown、图片、PDF、Office 等预览会重新加载内容
-
当前目录发生变更时，目录预览会重新加载子文件列表
-
文件树会自动刷新根节点和已展开目录，文件选择器缓存也会同步失效
-
如果系统无法精确判断变更路径，会触发保守刷新，确保预览内容不长期停留在旧版本
正在编辑文件时，系统不会静默覆盖未保存内容。此时可以手动刷新或保存后重新打开预览。
会话文件路径
会话中的文件链接可以直接在当前文件来源中打开。Agent 返回绝对路径时，系统会根据主空间或该会话固化的执行环境根目录转换为相对路径，再交给文件预览接口处理。
对于主空间使用 Sandbox、会话选择 Local 执行环境的情况，系统使用执行环境目录而不是主空间目录进行转换。完整目录仅用于路径规范化；文件是否允许读取仍由服务端依据空间权限、执行环境和允许根目录校验。
预览标签页管理
文件预览以标签页（Tab）形式呈现，交互体验与 VSCode 类似，支持多文件同时打开和固定：
打开文件
-
单击文件树中的文件：以预览模式打开（Tab 标题显示为斜体），再次单击其他文件时会自动替换
-
双击文件树中的文件：打开并自动固定该 Tab（Tab 标题恢复正常样式），不会被后续打开的文件替换
固定 / 取消固定 Tab
-
右键点击 Tab 标题，在右键菜单中选择"固定"即可固定该 Tab
-
已固定的 Tab 会在右键菜单中显示"取消固定"选项
-
固定的 Tab 不会因为打开新文件而被自动关闭
关闭 Tab
-
点击 Tab 上的关闭按钮
-
右键 Tab 标题选择"关闭"
-
关闭所有 Tab：右键任意 Tab 选择"关闭其他"或"关闭所有"
Markdown 预览
基本功能
Markdown 文件（.md）支持实时渲染预览：
-
标题层级
-
列表（有序/无序）
-
代码块（语法高亮）
-
表格
-
链接和图片
-
引用块
示例效果
# 标题一
这是一段普通文本，**粗体** 和 _斜体_。
## 标题二
- 列表项 1
- 列表项 2
| 列1 | 列2 |
| --- | --- |
| A | B |语法高亮
代码块支持多种编程语言的语法高亮：
```javascript
function hello() {
console.log("Hello, World!");
}
```支持的语言包括：JavaScript、TypeScript、Python、Java、Go、Rust、SQL、Bash 等 50+ 种语言。
数学公式
支持 LaTeX 数学公式：
行内公式：$E = mc^2$
块级公式：
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + ... + x_n
$$图片预览
支持格式
| 格式 | 扩展名 | 特点 |
|---|---|---|
| PNG | .png | 支持透明背景 |
| JPEG | .jpg, .jpeg | 适合照片 |
| GIF | .gif | 支持动画 |
| SVG | .svg | 矢量图形 |
| WebP | .webp | 现代格式 |
预览功能
-
自适应显示
-
点击放大
-
缩放和拖拽
-
显示图片信息
图片操作
在图片预览中：
-
滚轮：缩放
-
拖拽：移动
-
双击：适应窗口
-
Esc：退出预览
PDF 预览
功能特点
-
分页显示
-
页面导航
-
缩放控制
-
全屏模式
操作方式
| 操作 | 方式 |
|---|---|
| 翻页 | 点击箭头或滚动 |
| 跳转 | 输入页码 |
| 缩放 | 点击 +/- 或滚轮 |
| 全屏 | 点击全屏按钮 |
限制
-
大型 PDF 可能加载较慢
-
不支持 PDF 表单填写
-
不支持 PDF 编辑
Word 文档预览
支持格式
| 格式 | 扩展名 |
|---|---|
| Word 文档 | .docx |
功能特点
-
在线预览文档内容
-
保留基本格式（标题、段落、列表等）
-
支持表格显示
-
支持图片显示
限制
-
仅支持 .docx 格式（不支持旧版 .doc）
-
不支持在线编辑
-
复杂格式可能显示略有差异
-
如需编辑请下载后使用本地 Office 软件
Excel 表格预览
支持格式
| 格式 | 扩展名 |
|---|---|
| Excel 表格 | .xlsx |
| CSV | .csv |
功能特点
-
在线预览表格内容
-
支持多工作表切换（.xlsx）
-
保留基本格式
限制
-
仅支持 .xlsx 格式（不支持旧版 .xls）
-
不支持在线编辑
-
复杂公式可能无法显示
XMind 思维导图预览
支持格式
| 格式 | 扩展名 |
|---|---|
| XMind | .xmind |
功能特点
-
在线预览思维导图结构
-
支持节点展开/折叠
-
保留基本样式
视频预览
支持格式
| 格式 | 扩展名 |
|---|---|
| MP4 | .mp4 |
| WebM | .webm |
| Ogg | .ogg |
| AVI | .avi |
| MOV | .mov |
| 更多 | .wmv, .flv, .mkv |
功能特点
-
在线播放视频
-
支持播放控制（播放/暂停、进度、音量）
-
支持全屏播放
音频预览
支持格式
| 格式 | 扩展名 |
|---|---|
| MP3 | .mp3 |
| WAV | .wav |
| Ogg | .ogg |
| 更多 | .aac, .flac, .m4a, .wma |
功能特点
-
在线播放音频
-
支持播放控制
代码文件预览
支持的语言
支持 50+ 种编程语言的语法高亮：
| 类型 | 语言/格式 |
|---|---|
| Web | JavaScript, TypeScript, HTML, CSS |
| 后端 | Python, Java, Go, Rust, C/C++ |
| 移动端 | Swift, Kotlin |
| 脚本 | Bash, PowerShell |
| 数据 | SQL, JSON, YAML, XML |
| 配置 | Dockerfile, Nginx, Apache |
功能特点
-
语法高亮
-
行号显示
-
代码折叠
-
搜索定位
文本文件预览
支持格式
-
.txt - 纯文本
-
.log - 日志文件
-
.ini, .conf, .cfg - 配置文件
-
.xml - XML 文档
-
.env - 环境变量文件
显示特点
-
等宽字体
-
行号显示
-
自动换行
-
搜索高亮
预览设置
主题设置
预览支持明暗主题：
-
跟随系统主题
-
手动切换
字体设置
代码预览的字体设置：
-
字体大小
-
字体族
-
行高
预览快捷键
| 操作 | 快捷键 |
|---|---|
| 关闭预览 | Esc |
| 缩放 | Ctrl/Cmd + 滚轮 |
| 重置缩放 | Ctrl/Cmd + 0 |
| 全屏 | F11 |
| 搜索 | Ctrl/Cmd + F |
分享文件
在文件预览中，您可以方便地将知识库文档分享给他人：
- 在预览界面点击工具栏的"分享"按钮
- 配置分享选项（有效期、访问密码、是否允许下载等）
- 生成分享链接发送给同事
目前仅支持组织内分享。更多分享选项和管理方法，请参阅 资源分享。
不支持预览的文件
以下文件类型暂不支持在线预览：
| 类型 | 扩展名 | 替代方案 |
|---|---|---|
| PPT | .pptx | 下载后本地打开 |
| 旧版 Office | .doc, .xls, .ppt | 下载后本地打开 |
| 压缩包 | .zip, .rar, .7z | 下载后解压 |
对于不支持预览的文件，可以：
- 点击下载到本地
- 使用本地应用打开
预览性能
大文件处理
-
大于 1MB 的文本文件可能显示警告
-
大于 10MB 的文件不支持预览
-
建议拆分大型文件
加载优化
-
图片懒加载
-
代码块按需渲染
-
PDF 分页加载
常见问题
Q：预览显示乱码怎么办？
A：检查文件编码，确保使用 UTF-8 编码。
Q：图片加载很慢怎么办？
A：检查网络连接，或压缩图片后重新上传。
Q：PDF 无法预览怎么办？
A：某些加密或特殊格式的 PDF 可能不支持预览，请下载后使用本地 PDF 阅读器。
Q：代码高亮不正确怎么办？
A：检查文件扩展名是否正确，系统根据扩展名判断语言类型。