Kivio Desktop

macOS / Windows 屏幕级 AI 助手：Agent 客户端，加上翻译、截图 OCR 与视觉问答

中文 · English · 更新日志

下载 · 功能 · 帮助 · QQ 群 1104450740

常驻托盘。热键翻译输入、选中文字或屏幕内容，框选后直接问 AI。打开客户端则是完整 Agent：工具、子代理、Skills、MCP、知识库、多模型并排。

自带 Key，无账号、无中转；数据只留本机，无遥测。

想出现在这里？欢迎通过 GitHub Issues 或 QQ 群 1104450740 联系。

点击折叠

感谢 合租巴士 赞助本项目。合租巴士 提供 GPT / Claude 等多款模型的官方稳定极速 API 中转服务，支持企业级定制、报销开票、7×16h 专属技术支持，更有独家适配的 WebSocket 连接方式，畅享极速首字速度。Codex 补贴倍率低至 0.08。点此注册。

屏幕上的字、框选的画面、本机已装的编码 CLI，不必拆成三套软件。Kivio 把它们收进同一个托盘应用：热键随时呼出，对话走你自己的供应商。

• 一个循环，多种宿主 — 内置 Agent、只读研究用的 Kivio Chat、以及本机外部 CLI（Claude Code、Codex、Cursor、OpenCode、Gemini、Kimi、Pi、Hermes、Grok、DeepSeek Harness），共用同一套聊天界面
• 屏幕级工具 — 快速翻译、选中翻译、截图翻译、替换翻译（译文画回原位置）；Lens 冻结屏幕后提问、标注，并可把对话交回客户端
• 自带 Key — OpenAI Chat Completions / Responses、Anthropic、Gemini、Grok（xAI Responses）；翻译、截图、Lens、每条对话可各用不同模型
• 扩展 — Skills、MCP、知识库、子代理、插件、连接器；右侧 Dock 带文件树、Git 与终端
• 跨平台 — macOS（Apple Silicon）与 Windows 10/11，Tauri 2 原生应用

聊天客户端	设置

完整记录见 Releases · 当前版本说明：v3.1.2

• 工具循环、子代理、Skills、MCP、知识库、附件；一问多模型对比
• 三种运行时：Kivio Agent（完整工具）、Kivio Chat（检索 / 抓取 / 知识库等只读能力）、外部 CLI
• 模型供应商的 API Key 可留空：聊天、获取模型和测试连接会直接请求配置的地址，不再要求填占位密钥；空密钥不发送密钥认证头，服务端返回的认证错误仍会显示。OAuth 方式仍需先登录。
• Goal 模式可通过底栏菜单或 Shift+Tab 选择：未发送的目标保存在当前会话草稿中，只保留一个 /goal 标签，底栏同步显示 Goal，输入框移到底部并将光标放在草稿末尾；切换到其他模式时移除标签、保留正文。
• 对话可交给本机已装的 Claude Code、Codex、Cursor、OpenCode、Gemini、Kimi、Pi、Hermes、Grok 或 DeepSeek Harness
• 可从本机 CLI 导入原生会话（钉在原 CLI 与原工作目录上续聊）
• 内置上下文面板区分总容量与分类：顶部显示最近主请求 API 实报的输入＋输出 Token，数值使用 k（如 53.0k/1000.0k），不使用万或百万缩写。分类合并为系统提示词（含设定、记忆等注入内容）、工具（含系统工具、MCP、技能）、对话（含消息、摘要、附件）；各行显示独立估算用量（≈）及明确标注的字符占比，按占比排序，只为已用区域分色。分类直接统计实际请求材料，不在刷新时重建另一份提示词；分项估算不按总量缩放，合计可能与顶部实报不同。平均缓存命中率只累计同时上报输入与缓存读取的主请求，按缓存读取 / 输入加权，缺失字段不按零计，低于 78% 或未知时隐藏。刷新、恢复和流式事件遵循同一计量序号，旧快照不覆盖新实报。无实报、压缩 / 清空后或切换模型时等待新实报，切回原模型也不复活旧值；本地估算不替代顶部实报，外部 CLI 保持自己的统计口径。
• 上下文弹层采用紧凑布局；无计量时只显示 —，不显示等待或待刷新提示，分类为空时不占位。刷新、压缩和清空操作仍保留。
• 手动与自动压缩使用同一压缩模型设置，按 Token 预算保留近期完整消息 / 工具轮次。超窗重试保留旧信息，不再丢弃最旧历史；摘要必须缩小上下文，自动压缩还须留出余量，否则保留原历史并报告失败。界面原始消息不删除。
• 媒体站：生成图片与视频；视频结果和创作记录详情在播放前加载首帧画面，不自动播放
• 聊天 SVG 渐进预览：svg 代码块和以 SVG 为根的纯 html 图形在生成中逐步显示；可切换源码，标签、属性或字符实体未完成时保留已有画面，包括 Markdown 补入末尾换行的情况。普通 HTML 页面仍在生成结束后隔离预览

• 快速翻译、选中翻译、截图 OCR 翻译、替换翻译
• Lens：热键冻结屏幕，框选（macOS 可点窗口）后提问，可画箭头 / 矩形 / 马赛克，可把对话交回客户端
• OCR：系统引擎（Apple Vision / Windows OCR）或可选 RapidOCR 离线包

• 全局热键（可改、带冲突检测）、托盘常驻、浅色 / 深色
• 用量统计、生命周期钩子、可选聊天窗口保活（关闭后隐藏而不是销毁）
• 墨墨桌宠：默认关闭，可从侧栏账号菜单「界面语言」下方的「桌面宠物」开关或托盘「显示墨墨桌宠」开启；两个入口与右键隐藏实时同步，切换失败保留原状态并提示重试。在应用现有进程中原生绘制，不新增桌宠 WebView 或外部进程。跟随思考、执行、回答、等待确认、完成和失败状态；单击戳一下、拖动移动、双击打开对应聊天、右键隐藏。开关和位置保存在本机，关闭后停止动画；没有喂养、打卡或死亡机制。
  • 桌面版是正面朝向、带小脚的蓝色小墨团，八种状态共用轮廓、五官比例和道具配色，不随点击或拖动拉伸。空闲轻微呼吸，思考时三点起伏，搜索时移动视线，工作时轻敲紧凑键盘，回答时嘴型变化，等待时显示问号，完成时笑眼轻跃，失败时短暂摇头。只有工作时显示键盘；状态小卡片和键盘带细边，在浅深背景上均可辨认。完成短暂反馈后回到闲置，失败提示与对应聊天入口保留到下一次运行；等待确认优先于其他运行状态。原生几何和动画由 src-tauri/src/desktop_pet/sim.rs 维护，不影响聊天页墨墨。
  • macOS 与 Windows 共用平面几何；身体和道具可见部分接收鼠标，透明空隙穿透。闲置时鼠标靠近会关注并停止闲逛；拖动不拉伸，松手保存并停留在拖放位置，不自动下落或吸附底边。只有放在工作区底边时才会空闲短距离活动，任务进行中或等待确认时不闲逛。系统「减少动态效果」停用动画但保留状态标记；隐藏停止更新，再次显示恢复保存的位置。
  • 陪伴行为不改变工作状态：空闲时轻微呼吸、眨眼和打盹，鼠标靠近或点击就清醒，底边闲逛时双脚交替抬起；减少动态效果时不播放这些动作。单击会搭一句话，持续空闲时约每四分钟说一句本地短句，不调用模型、不增加 Token 费用。文字使用居中贴近墨墨、按内容收缩的圆角原生小气泡：浅色主题白底深字，深色主题深底浅字，随主题更新，十秒后收起；拖动、隐藏、锁屏和任务状态变化会撤下旧话，不排队补播。
  • 今日 Token 与费用分开用一句话播报，复用用量统计的本地日历日和计费口径，仅包含 Kivio 已记录调用，外部 CLI 未回传的用量不在其中。费用可能含估算，缺失费用不按免费展示；读取失败或记录不完整会说明，不编造数字。异步读取不阻塞动画，过期结果不会重新弹出气泡。
• 电脑操控：同一窗口内切换页面保留安装 / 更新进度；后台完成后刷新工具状态，失败提示保留并允许重试
• 页面任务：技能与插件安装、模型下载、媒体提交、原生会话导入、对话库批量处理及归档 / 删除 / 导出在同一窗口内持续执行；返回可查看进度、结果或失败提示，同一运行中的操作不会重复提交。技能与媒体站保留当前视图；技能卸载后商店恢复安装入口，旧预览、媒体引用和 Pi 安装回调不覆盖更新的草稿或反馈。前端状态保留限于当前窗口，不是应用重启恢复机制。
• 编辑草稿：笔记与自动化保存跨页面继续；笔记导航前同步读取编辑器正文，避免延迟回传丢字。助手只在手动保存时写入，旧删除或复制回调不清除、替换另一编辑会话。返回任务页恢复原自动化画布；加载远端新版本时同步更新画布，迟到读取不覆盖期间产生的编辑，包括已经保存成功的版本。
• 笔记页面及其富文本编辑器在首次打开笔记时按需加载，不参与聊天启动预加载；同一窗口后续打开复用已加载模块。
• TinyFish 授权：离开页面取消当前授权；再次进入只接受新授权的结果，不保存旧流程迟到的凭据。

• 设置 → 主题：独立管理显示模式、半透明侧边栏和主题库；内置中性、暖白、冷白，以及参考 T3 Code 配色适配的石墨、樱粉、森林、海湾、余烬、鸢尾，另有纯白、北欧 Nord、日晒 Solarized，共十二套主题，均包含浅色与深色色板。纯白的浅色主背景为 #FFFFFF，区别于中性的奶白；Nord 使用冷灰蓝与冰蓝强调，Solarized 使用米黄 / 深青底色与青绿强调。原有九套配色保持不变。
• 主题卡片同时展示明暗缩略图，支持方向键选择预览。复制内置主题创建自定义主题，颜色按表面、文字与边框、强调色、危险状态分组，可用取色器或 HEX 输入编辑；编辑时显示实时预览，窄窗口自动改为单列。预览不影响当前界面；保存后点击「应用主题」切换。正在使用的自定义主题保存修改后立即更新。
• 编辑草稿在设置页之间切换时保留，保存失败可重试；删除正在使用的主题后回到中性主题。主题随本机设置及设置备份保存。
• JSON 分享：导出弹窗显示完整 JSON，可直接复制；导入弹窗粘贴 JSON 后读取、预览并保存，Escape 关闭并恢复原按钮焦点。格式为 version: 1，theme 包含 name、light 和 dark；每个色板必须包含全部 17 个颜色字段，值为 #RRGGBB。导入分配新 ID，不覆盖同名主题；不支持任意 CSS。
• 界面表面与文字使用语义主题颜色：聊天消息、审批与提问卡、运行时菜单、Markdown 图表、自动化画布、用量统计、Lens 控件、图片查看器和知识库设置均随主题切换；正在使用的自定义色板修改后同步更新。截图和图片像素、品牌图标、语法高亮及状态标识保留各自颜色，不做全局白色替换。
• 刷新首屏在应用脚本和后端设置加载前同步恢复上次已应用的明暗色板，加载背景随主题显示；跟随系统模式会重新读取当前系统明暗。首屏缓存只保存颜色，不保存供应商或凭据，后端设置读取后覆盖缓存；内容外壳挂载后恢复透明画布，保留原生材质和截图浮窗透明性。浏览器存储不可用时仍正常应用后端主题。

都是开关，可在设置里改。

• macOS：Apple Silicon（.dmg 未签名）
• Windows：Windows 10 / 11（需要 Edge WebView2，系统通常已带）

从 Releases 下载：

• macOS：Kivio.Desktop_*_aarch64.dmg
• Windows 安装包：Kivio.Desktop_*_x64-setup.exe
• Windows 便携版：Kivio.Desktop_*_x64-portable.zip（解压即用）

macOS 首次请右键打开，或：

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

macOS 需要辅助功能与屏幕录制权限。启动后按引导填供应商即可。

• 更新日志 — 各版本下载与亮点
• 问题反馈
• QQ 群 1104450740

1. 安装并打开 Kivio，完成首次引导（供应商 + 热键）。
2. 添加供应商：设置 → 供应商 → 添加驱动 → 选预设（或自定义），填入 API Key。
3. 聊天：⌘⇧K / Ctrl+Shift+K 打开客户端，选模型后发送。需要本机 CLI 时，在运行时选择器里切换。
4. 屏幕：用热键翻译或打开 Lens；需要的权限在系统设置里打开。

npm install
npm run dev          # Rust + UI（macOS 会编 Swift sidecar）
npm run dev:ui       # 只开 Vite
npm run lint
npm run typecheck
npm test

# macOS / Linux
cargo test --manifest-path src-tauri/Cargo.toml

# Windows（请用脚本；直接 cargo test 的测试二进制可能起不来）
powershell -File scripts/win-cargo-test.ps1

npm run protocol:generate
npm run protocol:check

┌─────────────────────────────────────────────────────────────┐
│                 前端（React 18 + Vite + Tailwind）            │
│   同一套 bundle，四个窗口：main / chat / lens / translate     │
└────────────────────────┬────────────────────────────────────┘
                         │ Tauri IPC · chat-protocol
┌────────────────────────▼────────────────────────────────────┐
│                  后端（Tauri 2 + Rust）                       │
│   AgentHost 循环（prepare → planning → rounds → synthesis）  │
│     ├─ GUI 聊天                                              │
│     ├─ 外部 CLI 代理                                         │
│     └─ 子代理                                                │
└─────────────────────────────────────────────────────────────┘

模型资料在公开仓库 kivio-models 维护。在「设置 → 关于 → 检查更新」点击「更新模型库」，即可更新模型名称、上下文、能力和参考价格，无需升级应用。更新成功后立即用于后续请求，保留用户自定义设置；启动时不自动联网更新，下载失败继续使用原库。

Kivio 发版时自动同步最新兼容的模型库，并让 macOS 和 Windows 携带同一个提交的快照。开发时 npm run models:check 校验内置数据，npm run models:sync 手动同步；可通过 -- --ref <模型库提交 SHA> 固定来源。遇到 GitHub API 限流，可设置 GITHUB_TOKEN 或指定提交 SHA。模型资料的修改和升版方式见模型库仓库的 README。

欢迎 Issues 与 PR。提交前请确保：

• npm run lint
• npm run typecheck
• npm test

较大的功能请先开 issue 讨论。议题约定见 docs/agents/issue-tracker.md。

GPL-3.0-or-later © ZM