安装

当前稳定版为 v2.8.9，从 GitHub Releases 获取对应平台安装包。

macOS

Apple Silicon 下载 Kivio.Desktop_2.8.9_aarch64.dmg，打开后拖入 Applications。系统要求 macOS 13 及以上（屏幕捕获基于 ScreenCaptureKit）。当前 DMG 未签名，首次启动请在 Finder 中右键 Kivio Desktop →「打开」，或执行：

xattr -cr "/Applications/Kivio Desktop.app"

首次使用以下功能时，系统会请求相应的隐私权限：

在「系统设置 → 隐私与安全性」中为 Kivio Desktop 打开对应开关即可，无需重启应用。

Windows

下载并运行 Kivio.Desktop_2.8.9_x64-setup.exe（NSIS），支持 Windows 10/11 x64。手动启动默认打开 AI 客户端；勾选开机自启后，启动时会附带 --from-autostart 参数直接进入后台，不弹出窗口。

更新

应用启动时会静默检查一次 GitHub Releases 是否有新版本（autoCheckUpdate，默认开启）。也可以在「设置 → 关于」手动检查；发现新版本后可直接在应用内下载安装包并启动安装。若 GitHub API 检查失败，界面会提供 Releases 页面作为手动下载兜底。

快速上手

从安装 v2.8.9 到第一轮智能体对话，再试一次屏幕工具与本地 Agent。

第一步 · 安装并启动

从 GitHub Releases ↗ 下载最新版：macOS Apple Silicon 使用 .dmg，Windows x64 使用 NSIS -setup.exe。macOS DMG 未签名，首次启动需要右键 →「打开」。详细权限与更新说明见 安装。

第二步 · 完成首次引导

首次启动会依次引导你添加模型服务商、可选配置联网搜索、确认全局热键。Provider 可以从 DeepSeek、OpenRouter、SiliconFlow、GLM、Ollama 预设开始，也可以手动填写任意 OpenAI Chat Completions、Anthropic Messages、Gemini generateContent 或 OpenAI Responses 兼容服务商。粘贴 API Key 后获取模型列表，并明确勾选要启用的模型。详见 模型服务商。

第三步 · 发起第一次对话

从托盘菜单选择「打开 AI 客户端」，在模型选择器里选中刚启用的模型，输入一个真实任务。默认 Act 模式会按需使用文件、Shell、网页、Python 等工具；Plan 只研究和制定方案；Orchestrate 会把可拆分工作并行派发给子智能体。

• 点击输入框旁的来源按钮，可以挂载知识库、启用 MCP 连接器或联网搜索。
• 第一次使用文件或 Shell 工具时，应用会请求一次「允许本对话读写文件与执行命令」授权。
• Stop 会中断当前生成，但已经产生的文本与工具结果会保留。

第四步 · 试试屏幕工具

按 ⌘/Ctrl+Alt+T 唤出划词翻译，或按 ⌘/Ctrl+Shift+G 唤出 Lens，圈选屏幕区域后直接提问。macOS 首次使用会请求辅助功能与屏幕录制权限。所有热键都是开关式且可重设，完整列表见 快捷键。

第五步 · 可选：切换本地 Agent

需要编码工作流时，可以使用内置的 kivio-code / kivio code 终端 Agent；也可以在 GUI 的运行时选择器中，把对话交给本机已安装的 Claude Code、Codex、Cursor、OpenCode、Gemini、Kimi、Pi 或 Hermes。外部 Agent 使用各自已有的登录与配置，Kivio Desktop 负责检测、流式展示和会话管理。详见 Kivio Code 与外部 Agent。

智能体对话

对话不止于回答 —— 智能体自主规划、调用工具、并行派发子智能体，全过程可见、可中断、可追溯。

代理循环

每一轮对话都会经过一个固定的循环（run_agent_loop）：

1. 准备 —— 组装系统提示（人格设定、已激活的 Skill、记忆、项目绑定），并根据当前模式（见下）决定这一轮可以使用哪些工具。
2. 规划与执行 —— 模型请求调用工具，Kivio Desktop 执行后把结果喂回去，模型再判断是否需要继续调用。这个过程反复进行，直到模型不再请求工具，或触及轮次上限。
3. 综合 —— 不再有工具调用后，模型做最后一次不带工具的调用，生成自然语言总结。若这一步失败，Kivio Desktop 会分级降级：重试 → 换一次干净的追问 → 直接从工具调用记录里拼装一份确定性总结 —— 保证这一轮不会白跑。
4. 完成 —— 最终答案、推理过程、工具调用记录打包展示并保存。

默认每轮对话最多 20 次工具调用（maxToolRounds，可在设置中调整为 1–100）；编排者模式会把这个下限提高到 40，因为编排需要额外的轮次来做规划、派发和汇总。

三种模式

上下文管理

Kivio Desktop 会在每次调用模型前估算即将发送的上下文大小；一旦超过该模型上下文窗口的 90%，就会自动压缩：

• 对话尾部约 20,000 token 的「最近窗口」始终原样保留。
• 更早的内容优先做「微压缩」（把旧的工具调用结果替换成一句占位说明），如果这样就能压回预算内，不需要调用模型。
• 否则会调用模型生成一份结构化摘要（意图、关键技术点、涉及文件、报错与修复、待办事项等九个板块），如果对话里已有一份摘要，新摘要会在其基础上合并更新，而不是从头重写。

压缩发生时，界面上会出现「正在压缩上下文…」的状态和一条分隔线，可以展开查看摘要内容；累计压缩 3 次以上会提示「这个对话已被压缩多次，准确性可能下降，建议开始新对话」。

点击 Stop 会立即中断当前生成 —— 已经产出的文本、工具调用结果会被保留在对话记录里，不会丢失这一轮已完成的工作；派生出的子智能体也会随之一起停止。

对话与项目

把一次对话绑定到某个本地文件夹（项目）后，文件工具里的相对路径会默认相对项目根目录解析，减少每次都要写绝对路径的麻烦；显式的绝对路径或 ~/ 路径依然可以访问项目之外的任意位置（见 内置工具 的安全边界说明）。

内置工具

文件读写、Shell、网页抓取、Python 沙箱 —— 智能体开箱即用的原生工具集。

文件操作

命令执行

bash 运行 Shell 命令（Windows 上走 PowerShell，其他平台 sh -c），支持 background、工作目录、超时（1 秒–5 分钟可调）。像 npm run dev、vite、cargo watch 这类开发服务器命令会被自动识别并转入后台运行，不需要手动加 background:true。

后台任务不会随本轮对话结束而被杀掉 —— 会一直跑到你用 kill_background 手动结束，或应用退出。用 bash_output 增量读取输出和状态；不带任务 ID 调用则列出当前所有后台任务。

网页抓取

web_fetch 抓取一个 URL 并转成可读文本，仅限 HTTPS；web_search（需配置搜索服务商 Key 才会出现）用于联网检索。

安全边界

单次读取上限 2MB（MAX_READ_FILE_BYTES），超出且未指定行窗口会提示改用 offset/limit。

Kivio Desktop 对文件/Shell 工具采用「无路径边界」模型：没有针对 .ssh、.gnupg、系统钥匙串等目录的硬编码写入拦截，显式的绝对路径或 ~/ 路径可以读写磁盘上的任意位置，.. 路径穿越也被允许。安全性由另一层机制保证：read/grep/glob/write/edit/bash 这一组工具需要在每个对话里获得一次性的「允许本对话读写文件与执行命令」授权，授权之后才能不受限地使用；此外部分高敏感的单次工具调用仍可能单独弹出一次性确认。项目对话里的相对路径默认解析到项目根目录，仅作为默认基准，不构成访问边界。

MCP 服务器

接入任意 Model Context Protocol 工具服务器，工具即插即用。

添加服务器

在设置里添加一个 MCP 服务器条目，支持两种连接方式：

• stdio（默认）—— 本地长驻子进程，填写启动命令、参数、环境变量；启动一次后保持连接，不会每次调用都重新拉起。
• streamable_http —— 远程 HTTP MCP 服务器，填写 URL（及可选请求头）；也支持完整的 OAuth 2.1 授权流程（PKCE + 动态客户端注册 + 本地回调），点一下「连接」，浏览器里登录授权即可，无需手动粘贴 Token —— 这套机制也是 连接器 里 Notion 等一键连接的底层实现。

部分服务器会被打上「连接器」标记（如 Notion、GitHub），归到设置里的连接器页面单独管理，但本质上仍是同一套 MCP 服务器配置。

管理与调试

MCP 服务器暴露的工具会动态并入模型可用的工具列表，与 Kivio Desktop 内置工具区别对待（内置工具走静态注册表，MCP 工具按服务器实时发现）。可以单独禁用某个服务器，或勾选只启用它提供的部分工具。

Skills

用 Markdown 定义技能，运行中按需激活，可挂载可执行脚本。

内置技能

自定义技能

一个 Skill 是一个包含 SKILL.md 的文件夹：YAML frontmatter（name、description 必填，可选 allowed-tools、triggers 斜杠命令别名、arguments 参数占位）加上 Markdown 正文。

三层扫描目录，后者覆盖前者（按 id 同名覆盖）：

• 内置 —— 应用自带资源目录
• 用户 —— 应用数据目录下的 skills/
• 外部 —— 设置里额外配置的扫描路径

激活方式：模型觉得相关时自己调用 skill 工具按名激活，或用户输入 / 加技能名手动触发（若技能声明了 triggers）。技能的完整正文默认不会预先塞进系统提示里，只有被激活的那一刻才注入 —— 这样可以装很多技能而不占用上下文。一旦技能声明了工具白名单，本轮对话可用的工具集会收窄到「技能运行时工具 ∪ Kivio Desktop 内置工具 ∪ 该技能允许的工具」。

子智能体

一条消息派发多个专职人格，并发执行，结果内联返回。

人格定义

三层覆盖，后者按 id 覆盖前者：

并行执行

子智能体通过 agent 工具调用 —— 阻塞式、单结果返回：每次调用都会等子智能体完整跑完，把最终结果整段返回给发起方，没有轮询或后台等待这类中间态。并行的方式是模型在同一条消息里发出多个 agent 调用，Kivio Desktop 会并发执行这些调用。

• 全局最多同时跑 12 个子智能体（可在设置里调整为 1–64）。
• 单轮最多并发执行 12 个工具调用（含 agent）。
• 子智能体最多嵌套 3 层，超过会被拒绝派生新的子智能体。
• 子智能体不能触发需要用户确认的敏感操作（会被自动拒绝），也没有待办清单工具 —— 它是纯粹的执行者，只有发起方能读写待办清单。

停止父对话会级联停止其下所有正在运行的子智能体；被取消的子智能体会明确标记为「已取消」而非「失败」，且不会重试。

Kivio Code 与外部 Agent

既可以使用 Kivio 自己的终端编码 Agent，也可以让已安装的第三方 CLI 接管 GUI 对话。

Kivio Code

kivio-code 是基于 Kivio Rust 智能体运行时构建的 CLI/TUI，也可通过主程序的 kivio code 子命令启动。它复用桌面端模型服务商设置，并提供独立会话、MCP 配置、Skills 装载、项目工作目录和只读模式。

# 进入交互模式
kivio code

# 在指定项目执行一次任务
kivio code -C /path/to/project -p "检查这个项目并修复测试失败"

# 只允许读取和分析，不允许 write/edit/bash
kivio code --no-approve -p "审查当前项目"

如果终端找不到 kivio，需要先把安装包内的可执行文件或自行构建的 kivio/kivio-code 加入 PATH。

外部 CLI Agent

聊天窗口的运行时选择器可以检测并调用本机的 Claude Code、Codex、Cursor、OpenCode、Gemini、Kimi、Pi 和 Hermes。选择某个外部运行时后，Kivio Desktop 会把当前提示与项目工作目录交给对应 CLI，并在 GUI 中持续显示输出、维护会话和停止状态。

• 外部 Agent 必须先独立安装并完成自己的登录或 API 配置。
• 检测结果按项目目录隔离；切换项目后会重新发现可用运行时与模型。
• OpenCode 会同时读取全局配置和项目目录中的 opencode.jsonc，因此项目级自定义服务商模型也会出现在选择器中。
• 设置中的「外部 Agent」页面可以查看检测状态、命令路径和可用模型。

怎么选择

知识库

向量 + 全文混合检索，RRF 融合，可选重排 —— 全部本地索引。

创建与导入

新建一个知识库时需要选定一个 Embedding 服务商 + 模型 —— 这个绑定是「一次性」的：库的向量维度由第一次真实调用的返回结果自动学习并固定下来。之后如果换一个 Embedding 模型，会清空重建整个索引（重新解析、重新向量化每一份文档），不是免费的操作，需要用户在弹窗里明确确认。

支持导入的格式：

• txt / md / csv / tsv —— 直接读取
• html —— 复用网页抓取的正文提取逻辑
• docx / xlsx / pdf（仅文字层）—— 内置解析器，单文件上限 20MB
• 图片（png/jpg/webp 等）—— 按「文档处理」设置里选定的 OCR 引擎识别后入库；OCR 引擎设为「关闭」时会拒绝导入图片

扫描版 PDF（没有文字层）目前不支持：选择「强制 OCR」策略也只会报错提示暂未启用，内置解析器只能读取 PDF 自带的文字层。

URL 导入会抓取网页正文并保存为一份 .md 快照（重新索引时不会再次联网抓取），按抓取内容的哈希去重 —— 重复导入同一篇未变化的网页是空操作。

检索配置

检索默认是混合模式：向量相似度和 FTS5 全文检索各自取一批候选，用 Reciprocal Rank Fusion（RRF）按排名融合打分，而不是简单加权分数。设置里可以：

• 关闭「Hybrid 融合」—— 退化为纯向量检索。
• 调整「向量权重」与「关键词权重」的相对比例（开启混合时才生效）。

重排（Rerank）是可选的全局设置，对所有知识库统一生效：配置一个兼容 Cohere/Jina 重排接口的服务商 + 模型后，检索结果会先多召回一批候选送去重排服务打分再排序截断。不配置时这一步直接跳过；重排服务调用失败也不会导致检索失败，只是退回混合检索本身的排序。

引用与溯源

把一个或多个知识库「挂载」到某个对话（聊天输入框的图书图标），模型才会用 knowledge_search 工具检索它们 —— 未挂载任何库时不会去搜索全部知识库兜底，而是提示模型请用户先挂载。

回答中引用某个检索片段时，模型会在正文里标注 [n]；界面上这是一个可点击的小徽标，点开会弹出该片段的来源文档名、标题路径和原文片段。展开对应的检索工具调用卡片，还能看到这一轮全部命中的来源列表。

代码沙箱

Pyodide 在本地 WebAssembly 里运行 Python —— 数据不出机器，断网也能算。

模型调用 run_python 工具执行代码，运行在一个没有主机文件系统访问权限的沙箱里 —— 不是在你的真实电脑上跑 Python，而是应用内置的一个虚拟环境，执行完全离线、随开随用。

可用包

以下包随应用打包，完全离线可用（无需联网）：

numpy · pandas · matplotlib · pillow · micropip · seaborn · openpyxl · xlrd · pypdf

图表和文本渲染内置了中文字体（Noto Sans CJK），中英文都能正常显示；沙箱字体不含 emoji/符号字形，这类字符会渲染成空方块。

scipy、sympy、scikit-learn、statsmodels 等未预装的包，以及任何其他 PyPI 包，会在导入时自动尝试联网安装 —— 这部分需要网络连接，离线环境下会失败。

产物导出

没有单独的「导出」工具 —— 沙箱运行前后会自动扫描虚拟文件系统里新增/变化的文件（图片、表格、CSV、HTML、Markdown 等），把它们作为产物提取出来，写入这次对话专属的交付目录（~/Kivio/outputs/<对话ID>/），并在聊天界面里渲染成可下载的文件卡片。

每次对话最多累计 16 个交付文件，超出时按最旧优先淘汰；这些文件会一直保留，直到对话本身被删除。

右侧 Dock

文件树、Git 审查、真实终端 —— 看着智能体改你的文件，而不是猜它改了什么。

聊天窗右侧可以拉出一条 IDE 式侧栏，绑定当前对话的工作目录：项目对话是项目根目录，非项目对话是该对话专属的工作区目录。内置运行时与外部 CLI 代理各自解析各自的目录，Dock 显示的始终是这一轮真正会被写入的那个。

宽度可拖拽调整，开合状态、宽度、当前页签与每个项目展开过的目录都会记住。

文件树

• 框选、Ctrl / Shift 多选，鼠标拖拽移动文件，批量删除。
• 内联新建与重命名：失焦即确认，出错时错误文字直接显示在行内；新建完成后自动选中并定位。
• 就地查看器：点文件即可查看，带行号，可编辑保存。二进制文件与超过 1MiB 的文件会被拒绝打开。
• 目录变动由文件系统监听器推送，不需要手动刷新。

Git 审查

工作目录是 Git 仓库时，这个页签列出改动文件并显示 diff。未跟踪文件的状态徽章用 A（新增）而不是 ?，免得读成未知错误。单个 diff 超过 512KB 会被截断。

Git 操作直接调用系统的 git 命令，遇到 index.lock 冲突会自动重试。

终端

真正的 PTY 终端（macOS 用 forkpty，Windows 用 ConPTY），不是命令输出的模拟回显 —— 交互式程序、颜色、光标控制都正常工作。工作目录与 Dock 一致。关闭会话时其子进程一并结束。

与工具卡片联动

智能体调用 write / edit 时，聊天里的工具卡片折叠行会直接显示 +N -N（增绿删红）。展开是富渲染 diff：带 @@ 行号列、词级差异高亮、整行铺色。

点卡片上的文件名会在右侧 Dock 里预览这个文件（write / edit 看 diff，read 看文件内容）。文件在工作目录之外时，用它所在的目录作为临时根目录打开。

生命周期 Hooks

在对话的 8 个时点自动跑一段脚本或发一个 HTTP 请求。

内置智能体运行时会在固定的生命周期事件上派发 Hook，用来做通知、埋点、外部联动这类事情。在设置的 Hooks 页添加、启停与编辑。

事件

两种 Hook

• 命令 —— 执行一段 Shell 脚本，事件载荷以 JSON 从 stdin 传入。
• HTTP —— 向指定 URL 发请求，可自定义方法与请求头，载荷为 JSON 请求体。

两种都可设置超时。除 stdin / 请求体外，命令 Hook 还能读到这些环境变量（与 Claude Code、Codex 的事实标准对齐）：

KIVIO_HOOK_EVENT · KIVIO_HOOK_NAME · KIVIO_CONVERSATION_ID · KIVIO_RUN_ID · KIVIO_WORKDIR · KIVIO_TOOL_NAME

行为约定

• fire-and-forget —— Hook 不会阻断工具调用，也不能改写工具参数或拦截执行。失败只在界面上报一条警告，不影响这一轮对话。
• 零 Hook 零开销 —— 一条 Hook 都没启用时，运行时完全不会走这条链路。
• 作用范围 —— 只对 Kivio Desktop 内置的智能体运行时生效；外部 CLI 代理（claude、codex 等）由各自的 CLI 驱动，不触发这些事件。
• 取消对话时，已经派发出去的 Hook 仍会正常收到结束事件，不会被吞掉。

划词翻译

全局热键唤出，流式出译文，提交即回填原应用。空闲仅 ~50MB。

使用

默认热键 ⌘/Ctrl+Alt+T（CommandOrControl+Alt+T）在鼠标位置唤出一个极简翻译窗口；再按一次或按 Esc 关闭。输入停顿 600ms 后自动发起翻译请求，结果流式显示。

翻译结果上按 Enter 提交：译文会写入系统剪贴板，窗口立即销毁（不是隐藏，回收内存）；如果开启了「自动粘贴」，还会在 600ms 后模拟一次粘贴快捷键，把译文直接贴回你刚才所在的应用（macOS 需要辅助功能权限）。

自定义提示词

设置里可以自定义翻译提示词模板，支持 {lang}（目标语言）和 {text}（待译文本）两个占位符；留空则使用内置默认模板 —— 要求完整直译、不改写不摘要、保留 LaTeX 公式、不加多余空行和评论。翻译单独使用「翻译」功能自己的服务商与模型设置，与聊天、Lens 等功能互不影响。

Lens 取景

圈选屏幕任意区域或窗口，画面直接进入视觉对话。

窗口与区域捕获

默认热键 ⌘/Ctrl+Shift+G 唤出一个全屏透明取景层，支持两种捕获方式：

• 悬停高亮 —— 鼠标移到某个应用窗口上会自动高亮整个窗口，松开鼠标（不拖拽）即捕获该窗口（macOS 支持窗口枚举；Windows 上以拖拽区域为主）。
• 拖拽圈选 —— 按住拖出一个矩形区域，松开即捕获该区域画面。

捕获后会弹出一个贴着选区的聊天输入框，可以直接输入问题追问 —— 支持多轮对话。默认情况下 Lens 的回答会转入完整的聊天窗口展示，而不是停留在悬浮的小窗口里。

联网搜索

Lens 可以在必要时自动联网搜索补充上下文（时效性信息、截图里不熟悉的名词/产品/地点等），支持 Tavily、Exa、Ollama、Grok 等搜索服务商 —— 这些 API Key 需要在 Lens 设置里单独配置，与翻译/聊天用的模型服务商密钥完全独立。是否搜索由一次轻量的规划调用自动判断，纯粹的截图翻译/摘要类问题不会触发搜索。

Lens 使用自己的服务商与模型设置（留空则回退到「划词翻译」的服务商与模型）。

截图翻译与 OCR

三种 OCR 引擎，任何环境可用。

引擎选择

三个独立的截图翻译热键：⌘/Ctrl+Shift+A（截图翻译）、⌘/Ctrl+Shift+T（翻译当前选中文字）、⌘/Ctrl+Shift+R（原位替换翻译，直接把译文叠加在原文上方）。

「原位替换翻译」这一功能固定使用 RapidOCR，与全局 OCR 引擎设置无关。

离线 OCR 安装

RapidOCR 需要手动安装：设置里点击下载按钮，会拉取 ONNX Runtime 运行库和识别模型文件（检测模型约 5MB + 识别模型约 10MB），保存到应用数据目录下的 rapidocr-models/。这是用户主动触发的一次性下载，应用不会自动帮你装。

截图翻译支持流式输出：译文先逐字显示，翻译完成后再流式显示识别出的原文（小字灰色，作为参考）；也可以在设置里关掉「显示原文」，只看译文。

模型服务商

四种原生协议直连任意提供商；每家可配密钥池，限额自动轮换。

协议

内置了几个预设，仅预填名称和接口地址，模型列表仍需自己拉取并勾选启用：DeepSeek、OpenRouter、SiliconFlow、智谱 GLM、Ollama。也可以完全自定义任意服务商。

密钥池与容灾

每个服务商可以配置一组 API Key（数组），第一个是主 Key，其余是备用。触发规则：

• 401 / 402 / 403（密钥失效、欠费、无权限）—— 立即切换到下一把可用的 Key。
• 429（限流）—— 先原地重试；同一把 Key 连续遇到两次 429，且存在其他没在冷却中的 Key 时才切换；如果没有备用 Key，就耐心重试而不是报错。
• 失效的 Key 会冷却 60 秒后才重新参与轮换；用成功了会立刻清除冷却状态。
• 5xx、超时、连接错误按普通网络问题重试，不会当成密钥问题去轮换。

「测试连接」按钮只测试第一把 Key —— 这是刻意设计：保证你能清楚知道主配置本身是否正确，而不会因为某个备用 Key 恰好能用而掩盖真正的配置问题。

按功能分配模型

划词翻译、截图翻译、Lens、聊天可以各自配置独立的服务商与模型：

• 划词翻译 —— 独立设置，不受其他功能影响。
• 截图翻译 —— 独立设置。
• Lens —— 留空则回退到划词翻译的服务商/模型。
• 聊天 —— 每个对话可在 ModelSelector 里单独切换模型；未指定时按「默认模型 → Lens → 翻译」的顺序逐级回退到第一个已配置的选项。

连接器

Notion 等远程数据源一键连接，令牌本地保管。

OAuth 连接

点击「连接」，系统默认浏览器打开对应服务的授权页面，登录并同意授权后自动跳回 —— 全程不需要手动复制粘贴任何 Token。内置目录里的 Notion 走这套流程；也支持连接任意实现了 OAuth 2.1 动态客户端注册的自定义远程 MCP 服务器，不限于预置列表。

Access Token 到期前会自动静默刷新，无需重新走一遍授权。授权信息（含 Token）保存在本地设置文件里。

本地连接器

• Obsidian —— 纯本地，读取 Obsidian 客户端自身记录的库列表，选定一个库路径即可；智能体通过普通文件工具读取笔记，不涉及 MCP 或 OAuth。
• 邮件（Himalaya） —— 基于 Himalaya CLI（可一键自动安装），填入邮箱账号 + IMAP/SMTP 信息即可；智能体通过内置的邮件 Skill 驱动这个 CLI 收发邮件。

快捷键

所有入口都藏在全局热键之后 —— 唤起时才出现，用完即走。

默认热键

每一个都是「再按一次即关闭」的开关式热键，且都可以在设置里单独禁用。

自定义

设置面板里点击热键输入框，直接按下想要的组合键即可录制，无需手动输入字符串。修饰键的常见写法（cmd/command、ctrl/control、opt/option/alt 等）都会被自动规范化成统一形式，不用担心大小写或别名问题。

保存前会做重复检测，如果新组合和另一个已启用的热键冲突，会在输入框旁提示冲突对象。留空即可完全禁用某个热键。

如果某个热键被操作系统或其他应用占用导致注册失败，保存会安全回滚 —— 所有热键都恢复到修改前的可用状态，不会出现「部分生效」的中间态。

设置项参考

主要设置分组一览。

设置保存在应用数据目录下的 settings.json（明文 JSON，包含 API Key —— 详见 设计理念 的本地优先原则；v2.3 及更早版本使用系统密钥串存储，升级后会一次性迁移进这个文件）。

常见问题

安装、密钥、网络等高频问题。

我的 API Key 存在哪里，安全吗？

保存在本机的 settings.json 里，明文存储，不上传任何 Kivio Desktop 服务器 —— 因为压根没有 Kivio Desktop 服务器参与请求转发。安全边界是你的操作系统账户权限，不是加密存储。

为什么某个功能提示「请先选择模型」？

该功能引用的模型不在对应服务商的「已启用模型」列表里（可能是服务商被禁用、模型被移除，或从未配置过）。去设置里为该功能重新选一个已启用的模型即可。

热键不生效/提示冲突怎么办？

大概率是被系统或其他应用占用了同一个组合键。设置面板会明确提示是「与 Kivio Desktop 自己的其他热键冲突」还是「被外部程序占用」，换一个组合键即可。

断网还能用哪些功能？

代码沙箱（run_python）里预装的包（numpy/pandas/matplotlib 等）完全离线可用；但任何需要调用模型的功能（对话、翻译、知识库检索的 Embedding/生成步骤）都需要网络连接到你配置的服务商。

更新日志

每个版本的变化。完整发布记录见 GitHub Releases ↗。

v2.8.9 · 2026-08-11

• 长对话性能大修 —— 消息列表重做虚拟化与滚动跟随：屏外消息卸载、流式行独立渲染、重内容延迟挂载。长对话打开更快，流式生成与回翻历史更流畅，修复多种滚动跳动与生成结束时的闪动。
• Kivio Chat 独立运行时 —— Kivio Chat 成为独立运行时，与 Agent 模式分开配置提示词。
• 新模型 —— 新增 Claude Opus 5 与最新 Gemini Flash；外部 CLI 新增 Kimi CLI 供应商配置。
• 发送与审批体验 —— 发送等待期间保留输入草稿与附件，消息真正进入发送流程后才清空；审批卡提交中禁用按钮并显示失败原因，可直接重试。
• 对话库与搜索 —— 全局搜索显示匹配片段并高亮跳转；修复从对话库打开对话的顺序问题；上下文用量面板收纳为三组。
• 界面修复 —— 恢复细胶囊滚动条并保持聊天滚动条可见，侧栏列表滚动时自动隐藏；统一设置面板头部与背景；CLI 供应商弹窗改为卡片分区。
• 安全与稳定 —— HTML 预览 iframe 沙箱化；Lens 覆盖层失活时后端强制关闭兜底；自动保存的设置在关闭窗口时同步到聊天视图。

查看 v2.8.9 Release notes ↗

v2.8.8 · 2026-08-08

• 对话库 —— 新增对话管理中心：搜索、书架分类、排序分组、多选批量操作、归档。插件管理改到设置页。
• 提示词缓存时长 —— 供应商可选择关闭、短时或长时缓存。
• 扩展中心中英文 —— 助手、技能、MCP、知识库、笔记、插件页面支持界面语言切换。
• 会话用量 —— 输入栏显示本会话的输入、缓存命中与输出 token 用量。
• 标题动画 —— 模型生成对话标题时，以打字效果替换临时标题。
• Cursor Composer —— 支持 Composer 1 / 1.5 / 2 / 2.5 等模型的上下文窗口与定价显示。
• 侧栏操作 —— 对话可钉选、一键归档；完整菜单改到右键；生成中显示波浪状态指示。
• 设置与用量统计 —— 调整设置导航顺序与记忆页布局；用量统计新增请求成功率。
• 问题修复 —— 修复流式中断后内容丢失、重复消息、滚动异常、批量删除残留，以及对话库切换闪白。

查看 v2.8.8 Release notes ↗

v2.8.7 · 2026-08-06

• 外部 CLI Agent 能力补齐 —— Claude Code 接入问用户、计划批准、后台任务和子代理实时进度；子代理调用独立显示为卡片。内置 Agent 改进读文件输出上限、上下文超窗压缩、空响应判定与用量统计。
• Pi 与 pi-btw 适配 —— Pi 原生供应商配置接入统一外部 CLI 体系，pi-btw 的事件映射进共享运行协议；流式中途断开时保留重试能力，并将上游断流与普通进程退出分开呈现。
• 长文本粘贴附件 —— 超长粘贴内容转换为内存文本附件，可查看和编辑，并完整覆盖持久化、重新生成、外部 CLI、导出和 steering 场景，不再静默丢失正文。
• 聊天交互与渲染修复 —— 修复 <details> 等标签被原样显示、中文相邻粗体不渲染、问用户答案折叠、图片右键菜单被 WebView 吞掉，以及流式滚动跟随被窗口 resize 竞态解除。
• 状态动效和暗色模式 —— 消息流末尾新增常驻运行状态行，后台任务计数与侧栏运行指示更准确；修复部分设备尤其暗色模式下的状态动画异常，并降低 WKWebView 悬停显隐引发的重绘成本。
• 记忆指令过滤 —— 收紧并修正记忆系统对命令字眼的安全匹配，避免正常内容被误过滤，同时清理输入区相关边界状态。
• OpenCode、模型与用量 —— 完善 OpenCode 原生供应商配置；外部 CLI 上下文用量按轮更新，新增首 token 延迟和思考档位记录，修复模型映射与统计口径。
• 其它体验改进 —— 支持生成中消息排队与立即引导，检查更新可就地执行，发送后为新消息留出阅读空间；设置页供应商与 CLI 分栏更紧凑，并修复 Edge/WebView2 密码可见按钮重复。

查看 v2.8.7 Release notes ↗

v2.8.6 · 2026-08-04

• 实时协议版本化 —— 聊天实时通信统一为单条 chat-protocol 通道：运行事件带版本与序号，会话事件带 revision，断线后按快照重放，类型与 JSON Schema 由 Rust 侧生成。同时修复会话持久化的并发竞争、侧栏刷新的全量扫盘与独占锁、单个订阅者异常中断整条流。
• 从本地 CLI 导入对话 —— 已绑定文件夹的项目可导入 claude / codex / grok / kimi / opencode 的原生会话，续聊仍由原 CLI 承担。历史为一次性快照，不与 CLI 同步。
• 供应商级请求配置 —— 每个供应商可单独设置自定义请求头（支持从 JSON / cURL 导入）、系统代理开关、prompt caching 与客户端身份。prompt 缓存新增覆盖 OpenAI 协议。
• 侧栏手动排序与对话钉位 —— 集与项目改为拖拽排序，展开后的对话可钉至指定位置，其余按更新时间排列；「最近」列表保持纯时间线。
• Grok (xAI) 独立为接口协议 —— 新增 xai_responses，按所选协议而非 base_url 分叉，正确处理 xAI 的字段限制、思考档位与响应留存行为。
• 重会话性能与滚动 —— 渲染策略改由成本估算决定，重会话切换耗时从约 1 秒降至接近瞬时；滚动跟随改按事件来源判定，修复贴底抖动与滚动条无法拖动。
• 聊天界面多语言 —— 常驻外壳（侧栏、标题栏、输入栏、顶栏选择器、右键菜单等）接入界面语言开关，新增 145 个中英条目。
• 退出清理 —— 修复退出时的 panic；此前会跳过外部 CLI 会话、后台命令进程组、OCR sidecar 与插件预览的清理，每次关窗都遗留子进程。
• 移除项（不兼容） —— 「流式输出」与「思考模式」开关已移除，两者恒为开启。

查看 v2.8.6 Release notes ↗

v2.8.5 · 2026-08-01

• 输入区与快捷键 —— 输入框上的选择器改为紧凑的按钮锚定弹层（助手 / 多模型 / 来源统一），上下文指示器与代码块外框重做；快捷键页新增「关闭聊天窗」，补上恢复默认与占用检测。
• 一 agent 一对话 —— 内置 Agent 的会话一旦有消息就锁定 agent 切换（此前只有本地 CLI 这么锁，中途换等于换个大脑接着同一段上下文）。
• 思考等级不再被静默降档 —— 四个适配器原样下发所选档位，能选哪几档由模型库门控，并可在模型详情里逐模型覆盖。
• 消息列表部分虚拟化 —— 只虚拟化更早的历史，最近一段始终实挂载；钉底不再抢用户滚动，读历史时脚下不再跳。
• macOS 图标适配系统外观 —— 感谢 @HappyDIY（#22）。
• 窗口材质与帧率 —— 修好台前调度切窗掉帧（macOS 材质改为常驻，焦点交给 AppKit）；Win10 没有 Mica 时不再误判材质生效、透出桌面。
• 运行时选择与界面细节 —— Kivio Agent 作为第一张卡片直接排进代理列表；上下文圆环换成 SVG 描边；内嵌设置页与首次引导变成浮起卡片；扩展页互切与弹层展开的第一帧不再闪。

查看 v2.8.5 Release notes ↗

v2.8.4 · 2026-07-31

• 右侧 Dock：文件树、Git 审查、真实终端 —— 聊天窗右侧新增按工作目录绑定的 IDE 侧栏。文件树支持框选多选、拖拽移动、批量删除、内联新建/重命名与就地查看编辑；Git 面板看改动与 diff；终端是真正的 PTY（forkpty / ConPTY）。工具卡片的 Write/Edit 显示 +N -N，展开是带行号列与词级高亮的 diff，点文件名即在右侧预览。
• claude CLI 改为一会话一常驻进程 —— 不再每轮重开子进程：首轮约 3.2 秒，之后每轮约 0.1 秒。换模型不再丢上下文；子会话（Task）不再把自述印进主回答、不再污染用量与压缩分母；停止改用 interrupt 控制请求而非杀进程。
• 上下文用量终于是准的 —— 所有外部 CLI 都漏算了 cache token（实测 kimi 97.6%、pi 62%、opencode 13%），且各家 cache 包含关系不同（codex 已含在 input 内，claude/pi/ACP 须相加）。分母也修了：claude 裸别名实测都是 100 万上下文，旧表一律按 20 万算，压缩在真实占用 20% 就触发。用量现在实时更新。
• MCP 改用官方 rmcp SDK —— 两套手写 JSON-RPC 合成一条通路，净删约 2270 行，「设置页测试连接」与「聊天里调用」不再表现不一致。顺带修好：远程 HTTP MCP 加了工具无需重启即可见；Windows 上 npx.cmd 这类 shim 不再找不到；装了企业 TLS 中间证书的用户从「连不上」变「能连」。
• 工具审批改为内联卡片，claude CLI 也会来问 —— 输入框上方的内联卡片：自然语言标题、只放路径或命令的代码块、带数字快捷键的三个动作，新增本对话「总是允许」。外部 claude CLI 接进同一条审批链路。并发审批不再只留最后一张卡（此前另外两张会静默超时被拒）。
• 对话生命周期 Hooks —— 内置智能体的 8 个生命周期事件可挂 Shell 脚本或 HTTP Hook，载荷走 stdin JSON + KIVIO_* 环境变量。fire-and-forget，不阻断工具调用；没配 Hook 时零开销。设置新增 Hooks 页。
• 子智能体角色通用化 —— 角色列表在运行时生成进 agent 工具描述（内置/用户/项目三层），不必再猜名字；字段照 Claude Code / Cursor 的 .md + frontmatter 事实标准，拷来的角色文件直接可用。支持工具通配、disallowedTools 继承减法与调用内临时角色。
• 界面：悬浮卡片式侧栏与 Windows 全宽标题栏 —— 侧栏/主区/Dock 改为三张浮起的卡片，侧栏支持系统级模糊材质（Windows Mica 跟应用主题）。Windows 三键改为贯穿全宽的 44px 标题栏带，内容不再留 132px 躲它。全站下拉栏统一规格、输入区拆三层、表格与代码块重做、等宽字体补 CJK 回退、macOS 顶栏那条线统一到同一基线。
• 图片右键菜单 —— 新增复制图片 / 图片另存为… / 查看大图（内嵌图与生成图两条路径都挂上）；大图查看器的复制与另存取原图而非缩略图。
• claude 模型清单剔掉 6 个退役 / 会被静默换掉的模型 —— 目录不等于可用：4 个已退役（选了只回退役警告），opus-4-1 / opus-4-0 更糟——不报错，直接给你 Opus 4.8。
• 稳定性与正确性修复 —— 退出不再留孤儿 claude 进程及其 MCP 子孙；外部 CLI 调过工具的回答不再渲染两遍；grok 的 token 用量在 _meta 里，此前一路读空；系统提示改走 --append-system-prompt-file，长会话压缩后不再静默失效；/cost 等客户端斜杠命令输出不再被吞；被截断的回答不再标成「完成」；探测不再堆空壳会话；流式思考不再逐帧抖动。

查看 v2.8.4 Release notes ↗

v2.8.3 · 2026-07-25

• 翻译 / 截图 / Lens 支持全部模型协议 —— 这三个功能此前把请求硬编码成 OpenAI 的 chat/completions 格式，配置成 Gemini、Anthropic 或 OpenAI Responses 协议的供应商一用就 404。现在与聊天共用同一套模型适配层，四种协议都能用。
• 修复 Gemini / Vertex 与 grok 拒绝工具调用 —— 内置工具 schema 中分支未标注类型的 anyOf 会让 Vertex 整请求驳回、grok 拒收工具定义，这些模型此前用不了工具；现已剥离并由运行时校验兜底。
• 内置联网搜索 —— 每个会话可选「关闭 / 内置 / 第三方」三态，内置模式直接调用供应商自带搜索（OpenAI Responses、Gemini、Anthropic），搜索过程以实时卡片显示在答案上方，最后一次选择记为新会话默认。
• 外部 CLI 全面重做 —— 全部 CLI 改用原生会话机制不再重放历史（kimi 迁 ACP，pi 用 --session-id）；错误分类并给出可操作引导；可用性与模型探测分离加缓存，第 2 轮起前置开销从 10–25 秒降到 500 毫秒内。
• Gemini 原生生图 —— 聊天里可用 Gemini 原生协议出图并挂到 artifacts；OpenAI 兼容中转出图也已打通，端点路由收敛为单一解析并在猜错时自愈。
• LaTeX 公式显示修复 —— 模型常用的 \[...\] 块级与 \(...\) 行内分隔符此前完全渲染不出来，现已支持。
• 从本地 CLI 导入 MCP 与 Skill —— 扩展页可扫描已安装的 Claude Code / Codex / OpenCode 配置并导入；MCP 改为启用与开窗时预热连接，首轮工具收集加短超时兜底。
• 独立截图标注 —— 新增箭头、矩形、马赛克标注，支持撤销后复制或保存；冻结帧双端常开，截图不再带鼠标指针。
• 新增 ego lite 插件 —— 启用时自动从仓库下载配套的 ego-browser Skill，随上游更新。
• 输入与界面修复 —— 所有输入框关闭 WebKit 智能输入（修自动大写与 autocorrect 插空格）；模型下拉按能力筛选（生图/视觉/embedding）；弹层与右键菜单按视口边缘自适应；对话搜索可全文匹配正文；输入框草稿跨对话保留；新增模型级 extra_body 透传。
• 稳定性修复 —— HTTP 连接池加保活（修长时运行后 error sending request）；请求调试 token 不再恒为 0；修复会话重复加载、多模型并答流式栏冻结、Retry-After 巨值长时挂起、后台命令未按会话隔离、检索 rerank 分被覆盖与结果静默截断。

查看 v2.8.3 Release notes ↗

v2.8.2 · 2026-07-20

• 笔记中心升级 —— 加入文件夹式管理与 Milkdown 实时预览编辑器，可把卡片移动到文件夹、用内联弹框管理文件夹。
• 消息区交互增强 —— 划词可「添加到聊天」引用进输入框，内置右键菜单支持复制选中/复制整条消息，并重构跟随滚动，修复流式不跟随与钉底闪动。
• 界面更个性化 —— 可自定义 UI 字号、界面字体与代码字体；头像改本地图片上传；记住上次模型与思考等级作为默认（移除「默认模型」设置），并精简翻译/资料设置。
• 连接测试更可靠 —— 测试连接按供应商 api_format 分派正确协议，改为模型批量测试，密码框去掉重复的原生眼睛图标。
• 外部 Agent 与体验细节 —— 本地 CLI 可接收图片/文件附件，可用性与模型探测拆分（不再频繁重复检测），移除 Kivio Code 终端 agent；修复暗色模式可见性；优化检索面板与知识库 tab；Lens 输入栏置于截图选区之上。

查看 v2.8.2 Release notes ↗

v2.8.1 · 2026-07-19

• 扩展中心 —— 新增 MCP 注册表市场（Official/Smithery/Glama）与技能商店（ClawHub + URL 安装），知识库整合进扩展中心，可在应用内浏览、安装、卸载。
• 知识库检索 —— 改为可度量的混合管线（向量 + 关键词 RRF 融合、可选重排、相关度阈值），并重做 RAG 设置页。
• 聊天界面动效 —— 扩展中心页面重构并统一动效令牌，视图/标签切换、右键菜单与弹窗均有入场/退场动画；macOS 交通灯对齐顶栏且拖动不跳动。
• 外部 Agent —— 新增 Grok CLI（xAI Grok Build）；Codex 走真实压缩 RPC 与真实上下文窗口；为 Anthropic 补齐悬空 tool_use 的合成 tool_result。
• 更快更省内存 —— 插件页秒开（消除打开时的 shell 探测开销），长时运行的运行时资源会被主动回收。

查看 v2.8.1 Release notes ↗

v2.8.0 · 2026-07-17

• 模型参数 —— temperature 改为可选且按模型生效，服务商请求遵循模型元数据，模型详情页展示更新后的能力与参数。
• 长对话体验 —— 底部跟随更稳定，虚拟列表重新挂载历史消息时不再重复播放入场动画。
• OCR 内存 —— RapidOCR 与图片修复模型在每次操作后释放内存，减少连续使用时的驻留占用。
• 本地 Agent —— Pi 正常结束不再触发收尾阶段 EPIPE；OpenCode 支持从全局及项目 opencode.jsonc 发现自定义模型。

查看 v2.8.0 Release notes ↗

v2.7.9 · 2026-07-16

• 产品统一更名为 Kivio Desktop，同时保持 kivio CLI、Bundle ID 与现有数据路径兼容。
• 修复 macOS 输入翻译 IME 崩溃，稳定 Lens/翻译浮窗生命周期。
• 远程 MCP 增加 OAuth 2.1、PKCE 与动态客户端注册支持。
• 改进首次引导、Lens 历史保存与 AI 客户端界面细节。

查看 v2.7.9 Release notes ↗