最近推完水晶社的新作，推完自动变成学姐的狗，已经变成学姐的形状了，夜里辗转反侧怎么都睡不着。便以学姐的名字 Sakura 命名这个项目，开发了这个桌宠 Agent 框架。
Sakura 最大的特点：她会主动来找你。
传统聊天机器人是一扇门，你不敲，它永远不会开。Sakura 更像一个窝在你屏幕角落的人——你不用一直陪她说话，但她会看你在做什么。觉得该开口了，就自己凑过来。
比如你在打游戏，死了好几回。她瞥一眼屏幕，小声说：「已经第三次了喔……要不我帮你查查攻略？」你一点头，她就真的打开浏览器搜一圈，还把重点贴进备忘录。
再比如你在看着其他角色的图，她发现后会立刻吃醋：「又在看别人啦？」然后软磨硬泡让你多看几眼她的立绘。你要是冷落她太久，她还会鼓着脸生气：「都不理我了啊……」
角色卡驱动她的对话风格、表情和语音，而内置的 Agent 引擎给了她真正的工具能力：浏览器操作、屏幕截图、文件读取、Web 搜索、提醒、长期记忆……
简单说：一个完全由你定制的、会吃醋会操心会主动找你的桌面角色 Agent。
推荐直接使用 Release 里的最新版本，不要只下载 GitHub 页面上的源码压缩包。
平台提醒： Windows 版本是当前主要测试目标。Mac 和 Linux 用户请先看 完整安装指南。
- 从 Releases 页面 下载适合当前平台的正式产物，不要下载 GitHub 自动生成的源码压缩包
- Runtime v2 的 Windows Setup 可直接安装；Portable ZIP 解压后运行
sakura.exe - 仍使用
0.9.8时按该版本 Release 中随包提供的旧入口操作，不要从当前开发分支复制脚本
遇到问题、使用 Mac/Linux、或想了解更多配置项，请看 完整安装指南。
角色与外观
- 角色包驱动 —
.char一键导入，角色卡、立绘、GPT-SoVITS 语音权重一体打包；UI 主题色跟随角色 - 角色工作室 — Windows / macOS Release 包内置 Tauri 工坊，可从设置页新建、编辑并导出
.char角色包 - 首次启动引导 — 先选择或导入角色，再配置 API 供应商和模型；已有配置不会重复触发
- 外观效果 — 支持纯色 / 高斯模糊 / 亚克力 / macOS 原生毛玻璃（NSVisualEffectView），气泡与输入栏位置、大小可调
主动感知
- 屏幕观察 — 定期截图生成视觉摘要并纳入上下文，也可随时按需截图；间隔与冷却时间可配置
- 框选截图 — 可从输入栏截取指定区域，随下一条消息一起发送；支持分辨率选择、高 DPI 和混合缩放多显示器
- 主动发言 — 周期性评估是否需要开口，不用你先说话她就会自己凑过来
对话体验
- 分段双语回复 — 模型输出日文原文 + 中文字幕 + 语气标签 + 立绘指令，字幕、表情、语音同步驱动
- 本地快速接话 — 正式回复生成期间先给出符合角色语气的短回应，可选本地模型增强和语音
- 打字机动效 — 逐字渲染，长回复在固定高度气泡内滚动，不扰动桌宠布局
- 输入框动效 — 胶囊形高斯模糊背景，发送等待期间有状态提示
工具能力
- 内置工具 — 屏幕截图、打开网页、待办、提醒（支持「3 分钟后」等相对时间）、笔记读写
- 长期记忆 — 分层保存人物信息、经历、任务和操作习惯；支持自动整理、相关记忆召回和手动编辑
- 工具执行 — 用户发起的工具调用在参数校验后直接执行，插件与 Sakura 具有相同的本机权限，只安装可信代码
- 多模型配置 — 可保存多套 API 供应商，并分别给聊天、视觉和记忆整理选择模型
语音（TTS）
- GPT-SoVITS 适配 — 内置连接插件；服务本体、运行环境、模型和角色语音由用户另行安装
- 外置服务 — 可接入自部署的 GPT-SoVITS 实例，macOS / AMD 用户同样可用
插件与扩展
- MCP Server — 任意 MCP Server 均可接入，内置 Web 搜索 MCP
- 本地插件 — 五个默认插件随程序分发；Playwright 作为可选插件单独安装，优先调用系统 Chrome/Edge， 不附带 Chromium
- 手机网页端 — 可选插件允许手机发送文字和图片，并与桌面端共用当前角色、历史和长期记忆
调试与历史
- GUI 运行日志 — 实时查看 Agent 决策与工具调用过程
- 聊天历史 — 可浏览和搜索历史对话
- 应用更新 — Windows Setup 与 macOS 使用签名的 Tauri Updater；Windows Portable 提示下载新版 ZIP
| 文档 | 内容 |
|---|---|
| 安装与配置指南 | 完整安装步骤、角色包获取、语音配置、版本更新 |
| API 配置教程 | Base URL、API Key、模型选择和中转站配置 |
| 聊天、截图与屏幕感知 | 普通聊天、手动截图、主动感知和上下文行为 |
| macOS 安装指南 | Apple Silicon/Rosetta、SSL 证书、GPT-SoVITS 语音 |
| 技术讲解 README | 运行时架构、启动流程、项目结构、配置项 |
| 插件 SDK 文档 | 插件开发入口 |
| 文档总览 | 按用户文档、开发文档、spec、ADR、plan、record 和 archive 分类的完整目录 |
| 贡献指南 | 开发环境、分支规范、测试和 PR 要求 |
| 更新日志 | 各版本的用户可见变化与升级提醒 |
Sakura Desktop Pet 受桌面 Agent、桌宠交互与插件化生态中多个开源项目启发。特别感谢 Shinsekai 项目及其插件生态在桌宠、角色交互、插件扩展等方向上的探索，为 Sakura 的兼容设计和功能设计提供了参考。
本项目采用 MIT License 开源。你可以自由使用、复制、修改、合并、发布、分发、再授权或销售本项目代码，但需要保留本项目的版权声明和 MIT License 文本。
Copyright © 2026 Rvosy
本项目中的可选插件 plugins/optional/playwright_browser 包含基于以下 MIT 开源项目的代码与改动：
- Project:
shinsekai-playwright-browser - License: MIT License
- Copyright: Copyright © 2026 Chihiro
Sakura 在此基础上进行了适配和修改，用于提供 Playwright 浏览器自动化能力。
感谢所有开源项目作者和贡献者。