文档核心能力

界面与聊天

本页讲窗口布局和一轮完整对话:模型怎么配、消息和附件怎么发、上下文何时压缩、每个消息按钮做什么。

窗口布局

应用使用无边框窗口加自绘标题栏:

  • 左侧显示当前工作区文件夹名,下面一条细红线。
  • 中间是拖拽区(data-tauri-drag-region),双击最大化/还原。
  • 右侧是 ⋯ 菜单和窗口按钮(macOS 在左,Windows/Linux 在右)。
  • ⋯ 菜单包含:打开应用数据目录、打开工作区目录、打开交付物目录(子智能体交换区 .data/deliver)、导出配置方案、恢复配置方案、Markdown 编辑器、反馈问题、关于 Rabbit Chat Studio。
  • macOS 上还会显示原生菜单栏(文件 / 编辑 / 工具 / 关于)。Windows 与 Linux 不画原生菜单栏,标题栏的 ⋯ 就是唯一菜单,剪贴板快捷键由 webview 原生处理。
  • 开启玻璃效果后窗口透明,背后的桌面由系统模糊(Acrylic,Mica 作为回退);只有外壳半透明,.messages 仍是不透明画布,阅读滚动不受影响。设置 → 外观会实时切换档位,宿主不支持时保留不透明画布。
  • 空对话(还没有消息)显示跳动的笑脸;自我进化「打盹」维护运行时,它会被进度行(阶段、轮次、工具调用数)替代,完成后留下一个可点击的结果气泡。

顶部工具栏:

按钮 用途
新建对话 清空当前会话并生成新的 session_id
智能体 子智能体列表与编排设置
技能 工作区技能,启用/编辑
MCP MCP 服务器管理
工具 内置工具开关、自动接受
历史 搜索、收藏、归档、重命名、删除会话
设置 外观、工作区、API、系统消息、高级、运行时、关于

按钮旁的小数字是已启用项的数量(技能、MCP 服务器、工具、智能体)。侧栏列表共用一套行样式:透明行、内嵌细线、悬停填充、相对时间,编排相关行折叠在一个展开项后面——只有启用模式常显。

模型配置

首次配置见 快速开始;这里说明每个字段的作用。

API 与模型

字段 用途
基础地址 OpenAI 兼容根地址,例如 https://api.openai.com/v1
API 密钥 以 Authorization: Bearer <key> 发送
模型 当前对话的默认模型
模型列表 底部模型选择器里可用的全部 id
从 API 获取模型 请求 /models 并匹配能力目录(两个请求进行中按钮会转圈)
手动添加模型 服务商没有 /models 时手动加 id
上下文窗口 所选模型的 token 窗口,用量条与压缩都用它
模型能力 工具、推理、视觉、文件、音频、开放权重、已弃用

能力徽标

能力目录把三个公开数据源(models.dev、OpenRouter、basellm/llm-metadata)合并成一份扁平快照 <app_data>/model_metadata.json,每周刷新、缓存 7 天;首次构建约下载 7 MB。条目按规范化名字(小写、扁平化)存放,所以查询先精确匹配,只有未知 id 才退回相似度打分。匹配结果显示成徽标并存进 config.model_metadata,影响:

  • 模型选择器里的图标;
  • 选择器允许的附件类型;
  • 是否出现思考深度选择器;
  • 智能体的上下文预算。

设置里会显示「匹配 <名称> · N% 相似度」,据此判断回退匹配是否可信。都没匹配上时应用保持宽松,不会拦截附件。

高级参数

设置 → 高级:

参数 说明
Temperature temperature,0–2;留空用服务商默认
Top P top_p,0–1;留空用服务商默认
最大完成 tokens model_settings.max_complete_tokens,单次回复上限
DS-Format 把 reasoning_content 回传给 DeepSeek 系思考模型;其它服务商请关闭

两个不同的限制:

  • 上下文窗口(model_context_lengths)是「整段对话能装多少」;
  • 最大完成 tokens 是「这一次回复能生成多少」。

思考深度

模型被标记为支持推理,或已经存过档位时,输入框旁会出现大脑图标选择器:

  • 默认(不发送 reasoning_effort,交给服务商决定)
  • 低 / 中 / 高

选择按模型存进 config.model_reasoning_effort[model],以 reasoning_effort 发送。服务商不认这个参数就保持默认。

发送与流式输出

  • Enter 发送;Shift+Enter 换行。
  • 输入 @ 引用工作区文件,/ 引用工作区技能——两个选择器都不抢焦点(见 输入框提及)。
  • +agent 在新对话里嵌入某个子智能体的角色,@@name 指向 .data/tmp 里的文件;往输入框粘贴或拖入文件,会复制到那里并以 @ 提及的形式附上。
  • 后台工作是成组展示的:运行中的后台任务和 serve 进程集中在发起它们的回复末尾,一张可折叠的后台卡片里,带运行/等待计数和中止/停止按钮。结果会交付给模型,不会作为聊天气泡打印到记录里。
  • 最新一条助手回复会镜像会话的工作计划:一张紧凑的待办卡片,带完成/总数和当前进行项。它会随会话恢复,所以重新打开的对话仍能看到当前计划;更早的回复保持干净。当这一轮以「等待定时器或外部事件」结束时,未完成的待办会被挂起,而不是被当成已完成;[goal:DONE] 控制标记不会出现在气泡里。
  • 每轮结束时,页脚给出这一轮的花费:tokens,以及服务商有报价时的金额——和延迟放在一起。
  • 回复通过 SSE 流式返回;生成期间发送按钮变成停止。实时尾部逐字符显现,连续淡入跨越分片边界,看起来像一次顺滑打字,而不是一块块跳变。
  • 生成期间输入框仍可用。 此时按 Enter 不会新开一轮,而是把文字追加到正在运行的这一轮:它会在下一个请求边界作为 user 消息送达,并在记录里标注为注入更新。如果回复已经发出最后一次请求,这个窗口已关闭,你的文字会作为正常的下一轮重新发送。
  • 停止会取消这一轮:主智能体停止,子智能体进程树被杀掉,剩余任务标记为跳过。
  • 支持推理的模型会显示可折叠的思考过程块;流式期间预览最后几行。
  • 代码块带复制按钮;公式用 KaTeX 渲染。
  • 生成期间不能切换历史会话,先停止。

流中断时

长时间思考不会被墙钟掐掉:请求不设总超时,只保留 120 秒读超时。此外:

  • 瞬时 HTTP 状态(429、5xx)会重试,并遵守 Retry-After;
  • 流中断即使已经吐出 tokens 也会重试——先丢弃死掉那次的尾部;
  • 因 finish_reason: "length" 被截断的回复会自动续写一到两次,而不是悄悄结束;
  • 没有 finish_reason/[DONE] 就关闭的流按错误处理,不当成完整回答;
  • 三次尝试后这一轮失败,错误在记录里可见。

输入框提及(@file、/skill)

输入框有两个内联选择器,取代了旧的回形针按钮:

  • @ —— 引用文件。 在词边界输入 @ 会弹出模型可能被展示的文件列表:工作区文件,跳过隐藏与 .gitignore 排除路径,上限 20000 条。↑/↓ 移动,Enter/Tab 接受,Esc 关闭;弹层不抢焦点。接受后把 @path 插入文本。
  • / —— 引用技能。 输入 / 列出工作区技能(.data/skills)。接受后把纯文本 /skill-name 插进消息——不附加任何东西,模型运行时用它自己的 use_skill 工具解析这个 token。
  • @@ —— 指向临时文件。 .data/tmp 下的文件(粘贴、拖入)用 @@name 就能引用,不用手打长路径。
  • + —— 嵌入子智能体角色。 在新对话里,+agent 直接用该子智能体的角色开始这一轮,不必打开智能体面板。
  • 同一时刻只开一个弹层:在词内部 @ 与 / 语法互斥,不需要叠加规则。

行范围

# 后缀把文本附件收窄到指定行:

提及 附加内容
@src/main.rs 整个文件
@src/main.rs#12-24 第 12–24 行
@src/main.rs#12- 第 12 行到文件末尾
@src/main.rs#12 只有第 12 行

无法按行切分的文件(图片、二进制)会附加整个文件并提示这一点。

PDF 提及按页计数

PDF 没有行,所以 # 后缀数的是页:

提及 转换内容
@paper.pdf 前 60 页
@paper.pdf#2 第 2 页
@paper.pdf#2-5 第 2–5 页
@paper.pdf#2- 第 2 页到最后一页

页面由内置的 pdf2md-rs 转成 Markdown 文本,像普通文本附件一样内联进提示词——不涉及模型能力,所以没有文件徽标的模型也能用 PDF 提及。细节:

  • 输入框上方有进度条显示转换(「正在转换 paper.pdf —— 第 3/30 页」),完成或失败后消失。
  • 转换结果缓存在 <workspace>/.data/tmp/pdf/<name>-<digest>.md;同一提及复用缓存,转换器升级会让缓存失效。
  • 提示词里的副本上限 6 万字符;缓存文件始终保存完整转换结果,需要时工具可以读剩下部分。
  • 转换失败(加密、扫描件、页码越界)按提及单独报告,绝不影响消息发送。

提及在发送时变成什么

发送时每个 @path 会被实体化为附件,下面的能力规则仍然生效:

类型 发送方式 需要的模型能力
文本(txt/md/代码/日志/JSON/CSV…) 内联进提示词 无;任何模型
图片(png/jpg/webp/gif/svg…) image_url 内容块 视觉
PDF(pdf) 转成 Markdown 内联(见上) 无;任何模型
音频(wav/mp3) input_audio 内容块 音频

细节:

  • 弹层只列出当前模型能接收的内容;换了模型后不支持的已实体化附件会被移除,并给出文件名提示。PDF 对所有模型都留在弹层里,因为它按文本发送。
  • 文本附件保留原文用于显示,同时也内联进请求。
  • 图片/PDF/音频以 data: URL 或 base64 发送;大文件会显著增大请求体积。上限:文本 8 MiB,二进制/图片提及 24 MiB(base64 之前)。
  • 附件属于当前输入框;定时器自动恢复不会带上你还在编辑的附件。
  • 记录里已发送消息会把 @path token(含 #行号 范围)和 /skill-name token 高亮成强调色片段;附件本身不再单独列在消息下方。

上下文用量与压缩

输入框上方一条细条显示当前请求占用上下文窗口的比例:

  • 生成中显示扫动动画;用量到达后显示真实百分比。
  • 到 90% 变成警告色。
  • 窗口取值顺序:model_context_lengths[model] → model_settings.max_tokens → 默认值。

请求接近窗口时(按约 4 字符/token 的预测性预检,含工具,并带饱和保护),后端自动压缩:

  1. 保留最近约 12 条消息,从干净的轮次边界开始。
  2. 用主模型把更早的历史总结成 9 段紧凑提示(意图、概念、文件、错误与修复、问题解决、全部用户消息、待办、当前工作、下一步);工具轮次压成一行流水账,机械式行摘要器作为兜底,保证压缩不会让这一轮失败。
  3. 把摘要作为带续写引导的用户消息,插在剩余历史之前——prompt cache 前缀保持稳定。
  4. 摘要与被覆盖的消息一起持久化;下一轮校验边界后丢弃已摘要的前缀,过期摘要直接作废而不是套用。
  5. 服务商仍报上下文溢出时,这一轮硬压缩一次并重试一次。

这不是「历史丢失」:原始消息仍在 SQLite 里,只是不再全部发给模型。

回复里的绘图

助手可以画图,图会以卡片形式出现在记录里:

类型 代码围栏 说明
流程图 flow JSON 节点/边;布局自动计算(dagre),颜色取自界面 token,浅色深色与配色自动跟随
3D 场景 carve 方块、球体、圆柱、平面、边与标签,带真实光照与接触阴影;拖拽可旋转
2D SVG svg 用界面 token 的内联矢量图
动态图 html-fig 需要动效或交互时用沙箱框架;受 CSP 限制、不能联网,且只在你同意执行后才运行
  • 关闭增强绘图开关时,图表改用 Mermaid。
  • 流程图可以无脚本动画(flow 沿每条边发送数据包,step 按层级依次显现),并且两次尊重 prefers-reduced-motion——构建时和输出的样式里各一次。
  • 每张图都有保存按钮:静态图存 PNG,动态图存 HTML。
  • 图不会漏进代码路径:它渲染在卡片里,不会以代码块出现在回答上方。

消息操作

把鼠标移到消息上会看到按钮:

按钮 出现位置 作用
重试 未完成的用户消息 重新发送该用户消息(例如出错/中断后)
导出 PDF 助手消息 把渲染后的消息写成 PDF 文件(不走打印对话框)
保存 绘图卡片 静态图存 PNG,动态图存 HTML
删除 持久化消息 从数据库删除该行
分叉 持久化消息 新建一个截止到该消息的会话,保留之前的上下文

用户附件显示为文件名小胶囊;图片显示缩略图。

定时器栏

助手用 timer_set 建了延时任务后,输入框上方会出现定时器栏:

  • 每个胶囊显示标签和倒计时。
  • 点 × 取消。
  • 定时器属于创建它的会话。它在你在别的会话时触发,会弹提示问是否把它的提示词插进当前输入框。
  • 待触发定时器会镜像到 <workspace>/.data/timers.json(按工作区);应用重启后重新装载,逾期的立即触发。
  • 有定时器待触发或回复正在流式输出时,应用会请求系统保持唤醒;持有该锁期间这条栏上显示已阻止休眠徽标。它只挡空闲休眠——屏幕仍可能变暗,合盖或电量策略仍可能挂起。

见 记忆待办与定时器。

提示词所有权

Rabbit Chat Studio 不注入默认人格。config.system_message 是你的基础提示词;请求只追加最少的运行时说明:

  • 操作系统信息;
  • 显式调用语法({tool:...}、{mcp:...}、{skill:...});
  • 可用技能(仅名称与描述;完整说明由 use_skill 加载);
  • 可用子智能体(仅开启编排时);
  • 记忆/定时器/待办策略(对应工具开启时);
  • 会话摘要与当前待办清单作为动态上下文。

你写的就是模型看到的基底。具体顺序见 提示词与上下文。

常见问题

现象 检查
发送按钮是灰的 输入为空且没有附件,或正在导出配置方案
@ 弹层显示「没有匹配的文件」 弹层只列模型可能看到的文件(跳过隐藏与 .gitignore 排除路径)——多打几个字符,或确认工作区
@ 引用提示「无法按行切分」 二进制/图片提及会附加整个文件;# 行范围只对文本有效(PDF 的 # 数的是页)
@paper.pdf 提及失败 加密或扫描版 PDF 无法转换;消息仍会发送,只是不带附件
选不了图片 模型没有视觉徽标;重新获取模型或换模型
没有思考深度选择器 模型未被判定为支持推理,且没存过档位
用量条一直扫动 用量还没返回;部分服务商不返回用量
停止后旧内容还在 停止只中断生成;已经生成的内容会留下
长回答提前结束 被服务商截断:应用会续写一到两次后报告——调高最大完成 tokens

源文件: docs/wiki/zh/interface-and-chat.md ↗ · 文档版本 v3.3.3