桌面宠物伴侣 OpenPetsHQ/openpets

桌面伴侣平台，带宠物、插件，还能选配本地智能体集成。

OpenPets 把一只会动的伙伴放到你的桌面上，再用插件把它变成专注搭子、提醒系统、小游戏、启动器，或者编程智能体的搭档。

by Boring Dystopia Development

其他语言版本：English | 日本語 | 한국어 | 简体中文 | 繁體中文 | Português (Brasil) | Español (LatAm)

下载 OpenPets

下载最新版 OpenPets 桌面版，然后启动它。宠物立刻就会出现，不需要配置任何智能体。

- 桌面宠物：会发呆、会乱走、会做出反应的动画伙伴，让你的工作区不再空荡荡。
- 官方插件：专注计时器、提醒、心情打卡、小游戏、启动快捷方式、喝水提醒，还有虚拟宠物属性。
- 插件 SDK v3：沙箱化的 JavaScript/TypeScript 运行时，用来给宠物开发新能力，支持权限、配额、存储、定时、命令、面板、事件、音频、通知等等。
- 可选的智能体层：Claude Code、OpenCode、Cursor、Devin、Pi 和 MCP 客户端都能驱动本地宠物做出反应，同时不会在气泡里泄露提示词、代码、路径、日志或密钥。

给 OpenPets 点个 Star

如果 OpenPets 让你的编程环境或桌面工作区多了点乐趣，欢迎给仓库点个 star。

用户篇：快速上手

你不需要是开发者，也不需要接任何 AI 智能体，就能玩 OpenPets。桌面应用配合官方插件阵容，开箱即用。

1. 安装 OpenPets 桌面版

从 OpenPets Releases 下载对应操作系统的安装包，Arch 系 Linux 也可以用社区维护的 AUR 包：

- macOS Apple Silicon：OpenPets--mac-arm64.dmg
- macOS Intel：OpenPets--mac-x64.dmg
- Windows：OpenPets--win-x64-setup.exe
- Linux：OpenPets--linux-x86_64.AppImage
- Arch Linux / CachyOS：用 paru -S openpets-bin（或 yay -S openpets-bin）安装 @pinoybear 维护的 社区 AUR 包 openpets-bin。

注意：Windows 发行版安装程序已签名。macOS 构建可能仍未签名，会触发安全警告；如果 macOS 阻止运行，用终端移除隔离标记： xattr -dr com.apple.quarantine /Applications/OpenPets.app

2. 管理和自定义宠物

在内置的 Pet Gallery 中浏览已安装的宠物、预览动画帧，并配置每个工作区或智能体窗口由哪只宠物来监视。

3. 启用官方插件

OpenPets v3 自带模块化的 Official Plugin Catalog。在桌面端 Control Center 中启用或配置插件，即可添加专注计时器、提醒和迷你互动游戏。

随附的官方阵容

- Day Routine：跟踪习惯，提醒你伸展身体或起身走动。
- Focus Buddy：番茄钟式专注计时器，帮你管理工作周期。
- Fortune Cookie：随机给出每日建议与智慧箴言。
- Launch Buddy：注册快捷命令，快速打开本地文件夹、项目或应用。
- Magic 8 Ball：向宠物提问，得到随机又有趣的答案。
- Mood Check-in：定期询问你的心情，关照情绪健康。
- Reminders：弹出可稍后提醒的铃声通知，支持自定义提示音。
- Virtual Pet：把桌面伙伴变成 Tamagotchi 式宠物，通过实时状态钉跟踪饥饿、亲密度和精力。
- Water Reminder：定期提醒喝水，提示可自定义，帮你保持水分。

插件平台与 SDK v3

OpenPets 插件系统提供安全、对开发者友好的 SDK（@open-pets/plugin-sdk），用来创建自定义伙伴行为。

安全与架构

- 沙箱运行时：每个 JS 插件都运行在沙箱化的 BrowserWindow 宿主环境中。
- 宿主渲染 UI：插件只描述动作、HUD 和通知，由桌面宿主负责渲染。HTML/JS 代码无法在宠物窗口内渲染原始 HTML 或执行任意脚本。
- 权限模型：权限必须在 manifest 中声明，并在安装时经用户批准。标记为敏感的 API（如 voice:listen、clipboard、pet:speak:dynamic）需要显式开启授权开关。
- SSRF 与私有主机防护：网络请求只能访问开发者声明的域名，并防止本地 SSRF。

SDK 接口（ctx）

插件通过 ctx 对象接入桌面环境，它提供：
- ctx.pets / ctx.pet：管理默认和生成的宠物实例：生成、移动、播放动画、做出反应。
- ctx.ui：弹窗、临时/固定气泡、自定义菜单、面板和状态 HUD。固定的迷你 HUD 气泡支持紧凑的 2x2 网格布局，带进度条，比如 Virtual Pet 的状态。
- ctx.audio：触发宿主管理的提示音，或用户导入的自定义音频。
- ctx.schedule：设置精确的定时器钩子（once、every、daily、cron、at）。
- ctx.ai / ctx.secrets：接入用户在宿主配置的 AI 服务商（Anthropic、OpenAI、Ollama），不会把 API key 暴露给插件源码。
- ctx.storage：简单的 JSON 键值存储，支持变更订阅。
- 其他 API：events、assets、bus、net（支持流式）、notify、voice（TTS 和按住说话 STT）、auth（PKCE 浏览器流程）、files（安全的系统文件选择对话框）、system、commands、status 和 log。

开发者工具与命令

用官方命令行创建、校验和测试插件。

1. 生成新插件

从任意官方模板（blank、reminder、ambient、ai-chat、tamagotchi、calendar）创建：
npx @open-pets/cli plugin new "My Plugin" --template tamagotchi

2. 校验

打包前检查 manifest 结构、权限和配置 schema：
npx @open-pets/cli plugin validate ./my-plugin

3. 测试框架

不用启动桌面应用就能编写确定性测试。用 @open-pets/plugin-sdk/testing 的 createTestHarness，你可以模拟宿主、推进时钟、触发动作并验证反应：
import { createTestHarness } from "@open-pets/plugin-sdk/testing";
import { register } from "./index.js";

const h = createTestHarness(register, { permissions: ["pet:speak", "schedule"] });
await h.start();
h.expectScheduled("decay");
await h.clock.advance("30m");
h.expectSpoke(/need attention/i);
在插件项目里运行插件测试：
npm test

进阶：智能体集成

如果你想让开发智能体驱动桌面伙伴，OpenPets 提供可选的本地 MCP（Model Context Protocol）集成层。

工作原理

配置智能体后，OpenPets 会暴露标准 MCP 工具。智能体可以在本地触发动画、更改状态、显示文字气泡：
1. Claude Code：安装 OpenPets MCP、在 ~/.claude/CLAUDE.md 写入记忆指令，并在 ~/.claude/settings.json 中安装钩子。
2. OpenCode：安装 OpenPets MCP、自定义项目指令文件，以及 @open-pets/opencode 自动钩子插件。
3. Devin Desktop + Devin CLI：把 OpenPets MCP 写入共享的 ~/.config/devin/mcp_config.json，同时为两者加上生命周期钩子（openpets configure --agent devin）。
4. Cursor / 其他 MCP 客户端：把 OpenPets 注册为标准 stdio 或 TCP MCP 服务器。

诊断你的配置

检查 Claude 钩子和项目级 Cursor MCP 集成是否已安装、需要更新，还是已经损坏，并确认桌面应用是否可达：
npx @open-pets/cli doctor
传入 --cwd <path> 可以检查另一个项目的 .cursor/mcp.json，传入 --json 则输出机器可读的结果。只有集成损坏时，这条命令才会以非零状态退出，所以在提 bug 之前跑一下很安全。

MCP 服务器配置

要把 OpenPets 当作 MCP 工具运行，先把服务器加进你的智能体配置： {
"mcpServers": {
"openpets": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@open-pets/mcp@latest"]
}
}
}
提示：想指定某只宠物，传入 --pet <petId> 参数。

可用的 MCP 工具

- openpets_status：获取目标宠物 ID，并检查运行时连通性。
- openpets_react：设置宠物反应动画（例如 thinking、editing、testing、success、error）。
- openpets_say：显示一条短气泡对话。

本地隐私与安全

- 所有自动反应都基于本地静态触发条件（例如命令运行时，或文件写入时）。
- 对话内容会经过校验，防止泄露敏感变量、路径、密钥或多行代码片段。
- 实时交互需要读写本地发现 token，保护 IPC 桥接不被外部网络触发。

开发工作区

适合为 OpenPets 代码库做贡献、测试改动，或在本地构建桌面安装包。

前置条件

- Node.js：20 或更高版本
- pnpm：11 或更高版本
- TypeScript：编译器支持

命令

安装项目工作区依赖：
pnpm install

以本地开发者模式启动 Electron 应用：
pnpm dev:desktop

启动并加载、监控官方插件：
pnpm dev:desktop:plugins

运行工作区类型检查、代码规范校验和测试：
pnpm check
pnpm typecheck
pnpm test

打包桌面应用： Build & package into target OS directory
pnpm package:desktop:dir

Build & package into final installer / setup archives
pnpm package:desktop

工作区结构

apps/desktop Electron desktop application
packages/client @open-pets/client (IPC helper library)
packages/mcp @open-pets/mcp (Model Context Protocol stdio server)
packages/claude @open-pets/claude (Claude integrations, memory, & hooks)
packages/opencode @open-pets/opencode（OpenCode 插件与指令配置） packages/pi @open-pets/pi（Pi 命令行扩展集成） packages/devin @open-pets/devin（Devin Desktop + Devin 命令行 MCP 配置与钩子） packages/agent-events 共享的清洗器与事件辅助包 packages/cli @open-pets/cli（面向用户的命令行入口，用于配置与脚手架） packages/sdk @open-pets/plugin-sdk（插件 SDK v3 声明与测试工具） packages/pet-format @open-pets/pet-format（宠物清单与 schema 类型） plugins/official 官方一方插件工作区（随宿主目录一起打包） docs/ 技术规范与架构文档

文档

在 docs/ 文件夹里可以找到详细的架构与平台文档：
- docs/architecture.md - 一页纸的心智模型：运行时拓扑、包主干、端到端流程。
- docs/desktop.md - Electron 应用：进程模型、托盘优先的交互、控制中心、安全模型。
- docs/agent-integrations.md - Claude Code、MCP、OpenCode、Cursor、Devin 和 Pi 各自如何配置。
- docs/plugins.md - 插件平台 SDK v3 清单、权限与沙箱运行时。
- docs/sdk.md - 面向插件作者的公开 SDK v3 契约：能力命名空间、权限范围、测试工具。
- docs/catalog.md - 宠物与插件目录契约：v3/v2、分页、安装产物。
- docs/development.md - 开发者体验：monorepo 布局、命令面、开发模式。
- docs/testing-and-validation.md - 质量关卡：行为测试、运行时检查、发布校验器。
- docs/release.md - 应用打包与发布流程。

归属与承诺

OpenPets 由 Boring Dystopia Development 开发和维护。没有基金会，没有投资人，没有隐藏议程——一个开放项目，有一个署名的所有者。把话说清楚：

- 代码是 MIT，并且永远是 MIT。 随便 fork、随便发布、随便改，孵化你自己的宠物。
- 本地优先，永远如此。 没有账号，没有注册，没有中心化 AI 服务器。AI 功能通过你配置的连接运行，用你的密钥，在你的机器上。
- 目录只是便利，不是缰绳。 宠物和插件从 openpets.dev 获取，但没有它应用也能完整运行。
- 用户不是生意。 OpenPets 永远不会把核心功能、插件 SDK 或智能体集成放进付费墙——也永远不会卖给你自己就能免费做出来的内容。

想支持这个项目：给仓库点个 star，孵化一只宠物，分享给朋友。

安全与隐私
- 仅限本地：OpenPets IPC 通过本地套接字/命名管道通信，每次运行都会生成随机安全 token 来加固。
- SSRF 防护：插件网络连接只允许访问已批准的域名，禁止访问本地网络/私有 IP。
- 动态内容净化：AI 语音产生的动态文本一律经过严格的本地过滤，抹掉路径、URL、密钥和多行代码片段。
- 敏感权限需同意：访问剪贴板、麦克风或动态 AI 回复的功能默认关闭，必须由你明确开启。

代码签名策略

OpenPets 的 Windows 发布产物只由项目的 GitHub Actions 可信构建工作流生成，并通过配置好的 SignPath 发布策略签名。公开的正式策略见 openpets.dev/code-signing-policy。

- 维护者、提交者、审核者与签名批准人：Alvin Unreal。
- 审核：改动发布工作流、签名配置或 Windows 打包方式，必须先经维护者审核，才能批准发布。
- 范围：SignPath 签名只用于 OpenPets 官方开源发布产物。
- 签名操作：SignPath GitHub 工作流遇到需要批准人审核的发布签名请求时可能暂停；批准必须在 SignPath 控制台完成，之后才能继续发布。
- 隐私：见隐私与网络行为策略。

免费代码签名由 SignPath.io 提供，证书由 SignPath Foundation 签发。