聊天
Elftia 的聊天系统是应用的核心交互界面，支持多标签页并行对话、消息分支与切换、流式响应实时展示、文件附件上传、会话组织管理，以及丰富的快捷命令和键盘操作。
使用场景
- 与 AI 进行多轮对话，获取建议、解答问题或协作完成任务
- 同时开启多个标签页，在不同话题之间自由切换
- 对 AI 回复不满意时，重新生成回复并通过分支导航对比不同结果
- 上传图片、文档等附件，让 AI 理解并分析文件内容
- 使用斜杠命令快速执行内置操作
- 通过
@符号引用项目文件，让 AI 了解代码上下文 - 使用
//快速插入预设提示词模板
多标签页
Elftia 支持同时打开多个聊天标签页，每个标签页拥有独立的会话上下文和消息历史。
操作步骤
- 点击标签栏的 + 按钮创建新标签页
- 在新标签页中开始独立的对话
- 点击不同的标签页在对话之间切换
- 右键点击标签页可以关闭或重命名
各标签页的消息、上下文和状态完全独立，不会相互干扰。
Tab Keep-alive（0.1.8）
切换标签页不会丢失状态：
- 切走再切回，保留滚动位置、未发送的草稿、流式状态
- 多个 tab 同时拉同一个 LLM 也不会互相覆盖（按 sessionId 隔离的流缓冲）
- 后台 tab 的轮询、动画自动暂停，不烧 CPU
设置页、Agents 页等非聊天页面同样应用 keep-alive：你切到设置改一半切回再回来，刚才在哪个 tab、滚到哪、改了哪些字段都还在。
消息分支
消息分支是 Elftia 聊天系统的核心特性之一。当你重新生成 AI 回复或编辑已发送的消息时，系统会自动创建分支，保留所有历史版本供你随时查看和切换。
分支创建方式
| 操作 | 结果 |
|---|---|
| 重新生成回复 | 在当前 AI 消息位置创建新分支，保留原始回复 |
| 编辑已发送的消息 | 从编辑位置创建新分支，后续对话基于修改后的内容继续 |
分支导航
当某条消息存在多个分支时，消息旁边会出现分支导航组件，显示：
- 分支图标 — 标识当前消息有多个版本
- 当前索引 / 总分支数 — 例如
2 / 3表示共 3 个分支，当前查看第 2 个 - 左右箭头 — 点击箭头在分支之间切换
使用步骤
- 将鼠标悬停在 AI 回复上，点击工具栏中的重新生成按钮
- 系统生成新回复并创建新分支
- 消息旁出现分支导航组件（如
1 / 2） - 点击左右箭头查看不同版本的回复
- 可以多次重新生成，每次都会增加一个新分支
:::tip 分支不会丢失 所有分支都会被持久保存。即使关闭应用后重新打开，分支历史依然完整可用。 :::
流式响应
AI 回复采用流式传输，消息内容会逐步实时显示在聊天界面中，而不是等待完整生成后一次性展示。
行为说明
- 回复生成过程中，消息区域会实时更新内容
- 消息底部显示加载指示器，表明回复仍在生成中
- 生成过程中可以随时点击停止按钮中断回复
- 中断后的部分回复会被保留
- Markdown 格式（代码块、列表、标题等）在流式过程中即时渲染
- 思考过程：推理模型的思考会以可折叠区域展示，写在最终回复上方
流式状态契约
每条 streaming 中的消息根 DOM 上有 data-streaming 与 data-stream-phase 标记，外部 driver（elftia-cli）可以可靠地等待消息完成。当 reasoning / tool-call / 内容 typing 任何一项还在进行中时，data-streaming 都为 "true"。这意味着 tool-call 结果延迟到达不会让流状态错误地变为 "false"。
富内容渲染
聊天系统支持多种富内容类型的内嵌渲染：
| 内容 | 渲染行为 |
|---|---|
| Markdown | 标题、列表、代码块（语法高亮 + 一键复制）、表格、引用块 |
| 图片 / 视频 | 内嵌预览，图片可打开 Lightbox 大图 |
| 音频 | 内置播放器 |
| 推理过程 | 可折叠区域，默认收起 |
| 工具调用 | 工具名 + 参数 + 结果，可折叠 |
| 内嵌 HTML | 检测到完整 HTML 文档（含 <!DOCTYPE> / <html>）时，以 iframe 形式安全渲染（沙盒不允许 same-origin） |
| Question Form（design session 专用） | 单选 / 多选 / 文本 / direction-cards 等问卷型消息，提交后转为答复继续对话 |
| JSON | 自动检测并格式化展示 |
附件上传
聊天支持多种方式上传附件，让 AI 分析文件内容。
上传方式
| 方式 | 操作 |
|---|---|
| 拖放上传 | 将文件从文件管理器拖入聊天输入区域 |
| 粘贴上传 | 使用 Ctrl+V 粘贴剪贴板中的图片 |
| 文件选择器 | 点击输入框旁的附件按钮，从文件对话框中选择文件 |
支持的文件类型
- 图片 — PNG、JPG、GIF、WebP 等常见图片格式
- 文档 — PDF、TXT、Markdown 等文本文件
- 代码文件 — 各种编程语言的源代码文件
上传的附件会在输入框上方显示预览缩略图，发送前可以点击移除。
会话管理
Elftia 提供完善的会话组织和管理功能，帮助你高效管理大量对话。
文件夹
- 在侧边栏创建文件夹，将相关会话归类整理
- 支持多级嵌套文件夹结构
- 拖拽会话到文件夹中进行归类
标签
- 为会话添加自定义标签，方便分类标记
- 通过标签快速筛选相关会话
搜索
- 在侧边栏顶部的搜索框中输入关键词
- 搜索范围涵盖会话标题和消息内容
- 搜索结果实时高亮匹配项
固定会话
- 右键点击会话，选择固定将其置顶
- 固定的会话始终显示在列表最上方，不会被新会话推下
命令菜单（/ 斜杠命令）
在输入框中输入 / 会弹出命令菜单，提供一系列快速操作。
使用步骤
- 在聊天输入框中输入
/ - 命令菜单弹出，显示可用命令列表
- 继续输入文字可以筛选命令
- 使用上下箭头选择命令，按
Enter执行 - 也可以直接点击命令执行
内置命令
| 命令 | 说明 |
|---|---|
/clear | 清空当前会话的消息历史 |
/help | 显示帮助信息 |
/model | 快速切换当前使用的 AI 模型 |
/settings | 打开设置面板 |
:::info 自定义命令 除内置命令外，Agent 系统和插件也可以注册自定义命令。具体命令列表取决于当前激活的 Agent 和已安装的插件。命令面板（slash palette）支持模糊搜索，按 Tab 自动补全参数。 :::
文件引用（@ 符号）
在输入框中输入 @ 可以引用项目中的文件，将文件内容附加到消息上下文中。
使用步骤
- 在聊天输入框中输入
@ - 弹出文件选择下拉菜单，显示当前项目的文件列表
- 输入文件名关键词进行筛选
- 使用上下箭头选择文件，按
Enter确认 - 文件引用会以标记形式插入到输入框中
- 发送消息时，被引用文件的内容会一并发送给 AI
:::tip 适用场景 文件引用功能在代码相关对话中特别有用。你可以引用源代码文件让 AI 分析代码逻辑、查找 bug 或提供优化建议。 :::
提示词快速插入（// 双斜杠）
在输入框中输入 // 可以快速插入预设的提示词模板。
使用步骤
- 在聊天输入框中输入
// - 弹出提示词快速插入菜单
- 菜单显示收藏的提示词、最近使用的提示词和提示词链
- 选择一个提示词模板
- 如果模板包含变量（如
{{language}}），系统会弹出变量填写表单 - 填写变量后，最终的提示词内容会插入到输入框中
详细的提示词管理请参阅提示词文档。
键盘快捷键
| 快捷键 | 操作 |
|---|---|
Enter | 发送消息（默认模式） |
Ctrl+Enter | 发送消息（Ctrl+Enter 模式）或换行（默认模式） |
Shift+Enter | 在输入框中换行 |
Esc | 关闭命令菜单或文件选择菜单 |
Up / Down | 在命令菜单或文件菜单中移动选择 |
Ctrl+V | 粘贴文本或图片 |
发送方式配置
你可以在设置中切换发送消息的快捷键方式：
| 模式 | Enter 键行为 | Ctrl+Enter 键行为 |
|---|---|---|
| Enter 发送（默认） | 发送消息 | 换行 |
| Ctrl+Enter 发送 | 换行 | 发送消息 |
在 设置 > 通用 中可以切换发送方式。
完整对话流程
以下是一次完整对话的典型流程：
输入消息 → 发送 → 流式响应实时展示
↓
对回复满意？
├── 是 → 继续对话
└── 否 → 重新生成（创建分支）
↓
分支导航切换对比
↓
选择满意的版本继续
常见问题
| 问题 | 解决方案 |
|---|---|
| 消息发送后没有回复 | 检查 LLM 提供商是否已配置 API Key，确认网络连接正常 |
| 流式响应中断 | 可能是网络波动或 API 超时，尝试重新生成回复 |
| 附件上传失败 | 检查文件大小是否超过限制，确认文件格式受支持 |
| 命令菜单不弹出 | 确保 / 是在输入框最开始或空格之后输入的 |
| 分支导航不显示 | 只有在消息存在多个分支时才会显示导航组件 |
@ 文件引用无响应 | 需要先打开一个项目，文件引用功能依赖项目上下文 |