安装

从 GitHub Releases 获取最新版本。

macOS

下载 .dmg，拖入 Applications。系统要求 macOS 13 及以上（屏幕捕获基于 ScreenCaptureKit）。

# https://github.com/ZMGID/kivio/releases/latest

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

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

Windows

下载 MSI 或 NSIS 安装包并运行，支持 Windows 10/11 x64。手动启动默认打开设置页；勾选开机自启后，启动时会附带 --from-autostart 参数直接进入后台，不弹出设置窗口。

更新

应用启动时会静默检查一次 GitHub Releases 是否有新版本（autoCheckUpdate，默认开启）。检测到新版本仅弹出提示，不会自动下载安装 —— 需要手动前往 Releases 页面下载新安装包完成更新。

快速上手

配好一把 API Key，几分钟跑通核心功能。

第一步 · 配置服务商

打开设置 → 模型服务商，新增一个 Provider：可以从内置预设（DeepSeek、OpenRouter、SiliconFlow、智谱 GLM、Ollama Cloud）里选一个快速填好接口地址，也可以手动填写任意 OpenAI 兼容 / Anthropic / Gemini / Responses 协议的服务商。粘贴 API Key 后点「获取模型列表」，再从中勾选启用你要用的模型。详见 模型服务商。

第二步 · 发起第一次对话

打开 Kivio Desktop 的聊天窗口，在模型选择器里选中刚启用的模型，直接输入问题发送。默认是 Act（普通）模式，模型会按需自主调用文件、Shell、网页等内置工具完成任务。

第三步 · 试试屏幕工具

按下默认热键 ⌘/Ctrl+Alt+T 唤出划词翻译窗口，或 ⌘/Ctrl+Shift+G 唤出 Lens，圈选屏幕任意区域直接提问。完整热键表见 快捷键。

智能体对话

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

代理循环

每一轮对话都会经过一个固定的循环（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 层，超过会被拒绝派生新的子智能体。
• 子智能体不能触发需要用户确认的敏感操作（会被自动拒绝），也没有待办清单工具 —— 它是纯粹的执行者，只有发起方能读写待办清单。

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

知识库

向量 + 全文混合检索，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 个交付文件，超出时按最旧优先淘汰；这些文件会一直保留，直到对话本身被删除。

划词翻译

全局热键唤出，流式出译文，提交即回填原应用。空闲仅 ~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 Cloud。也可以完全自定义任意服务商。

密钥池与容灾

每个服务商可以配置一组 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 ↗。