桌面宠物伴侣OpenPetsHQ/openpets

一个带有宠物、插件和可选本地智能体集成的桌面伴侣平台。

OpenPets 在你的桌面上放置一个动画伴侣，然后通过插件让它变成专注伙伴、提醒系统、小游戏、启动器或编码智能体助手。

由 Boring Dystopia Development 出品

 
 
 

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

下载 OpenPets

下载最新的 OpenPets 桌面版 并启动它。宠物会立即出现；无需设置智能体。

- 桌面宠物：会待机、游荡、做出反应的动画伴侣，让你的工作空间不再空荡荡。
- 官方插件：专注计时器、提醒、心情签到、小游戏、启动快捷方式、补水提醒和虚拟宠物状态。
- 插件 SDK v3：一个沙盒化的 JavaScript/TypeScript 运行时，用于构建新的宠物能力，支持权限、配额、存储、计划任务、命令、面板、事件、音频、通知等。
- 可选智能体层：Claude Code、OpenCode、Cursor、Pi 和 MCP 客户端可以驱动本地宠物反应，而不会在对话气泡中暴露提示词、代码、路径、日志或密钥。

为 OpenPets 加星

如果 OpenPets 让你的编码环境或桌面工作空间更有趣了一点，请给这个仓库点个星。

面向用户：快速上手

你不需要是开发者，也不需要连接任何 AI 智能体，就能享受 OpenPets。桌面应用搭配官方插件阵容，开箱即用，功能完整。

1. 安装 OpenPets Desktop
从 OpenPets Releases 下载适用于你的操作系统的安装包：

- 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

注意：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 或执行任意脚本。
- 权限模型：权限必须在清单中声明，并在安装时由用户批准。被标记为敏感的 API（如 voice:listen、clipboard 和 pet:speak:dynamic）需要显式同意开关。
- SSRF 与私有主机防护：网络抓取请求仅限于开发者声明的 hostname，并针对本地 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 密钥暴露给插件源代码。
- ctx.storage：简单的 JSON 键值存储，支持变更订阅。
- 其他 API：events、assets、bus、net（支持流式传输）、notify、voice（TTS 和按键说话 STT）、auth（PKCE 浏览器流程）、files（安全的操作系统选择对话框）、system、commands、status 和 log。

开发者工具与命令

使用官方 CLI 创建、验证和测试插件。

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

2. 验证
在打包前验证清单布局、权限和配置模式：
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（模型上下文协议）集成层。

工作原理
当你配置一个代理时，OpenPets 会暴露标准 MCP 工具。代理可以在本地触发动画、更改状态并显示文本气泡：
1. Claude Code：安装 OpenPets MCP、在 ~/.claude/CLAUDE.md 中写入记忆指令，并在 ~/.claude/settings.json 中安装钩子。
2. OpenCode：安装 OpenPets MCP、自定义项目指令文件，以及 @open-pets/opencode 自动钩子插件。
3. Cursor / 其他 MCP 客户端：将 OpenPets 注册为标准 stdio 或 TCP MCP 服务器。

诊断你的设置
检查 Claude hook 和项目 Cursor MCP 集成是否已安装、需要更新或已损坏，以及桌面应用是否可达：
npx @open-pets/cli doctor
传入 --cwd  以检查其他项目的 .cursor/mcp.json，或传入 --json 以获取机器可读的输出。仅当某个集成损坏时，该命令才会以非零状态码退出，因此在报告 bug 之前运行它是安全的。

MCP 服务器配置
要将 OpenPets 作为 MCP 工具运行，请将服务器添加到你的 agent 配置中：
{
"mcpServers": {
"openpets": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@open-pets/mcp@latest"]
}
}
}
提示：要指定特定的宠物，请传入 --pet  参数。

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

本地隐私与安全
- 所有自动反应均基于静态本地触发器运行（例如当命令运行或文件被写入时）。
- 语音内容会经过校验，以防止泄露敏感变量、路径、密钥或多行代码片段。
- 实时交互需要本地发现令牌的写入/读取，从而保护 IPC 桥接免受外部网络触发。

开发工作区

用于为 OpenPets 代码库做贡献、测试更改，或在本地构建桌面软件包。

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

命令

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

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

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

运行工作区类型检查、代码一致性验证和测试：
pnpm check
pnpm typecheck
pnpm test

打包桌面应用：
构建并打包到目标操作系统目录
pnpm package:desktop:dir

构建并打包为最终安装程序 / 安装归档
pnpm package:desktop

工作区结构
apps/desktop              Electron 桌面应用
packages/client           @open-pets/client（IPC 辅助库）
packages/mcp              @open-pets/mcp（Model Context Protocol stdio 服务器）
packages/claude           @open-pets/claude（Claude 集成、记忆与 hooks）
packages/opencode         @open-pets/opencode（OpenCode 插件与指令配置）
packages/pi               @open-pets/pi（Pi CLI 扩展集成）
packages/agent-events     共享的清理器与事件辅助包
packages/cli              @open-pets/cli（用于配置与脚手架的用户入口 CLI）
packages/sdk              @open-pets/plugin-sdk（插件 SDK v3 声明与测试工具）
packages/pet-format       @open-pets/pet-format（宠物清单和模式类型）
plugins/official          官方第一方插件工作区（随宿主目录捆绑）
docs/                     技术规范和架构文档

文档

在 docs/ 文件夹中探索详细的架构和平台文档：
- docs/architecture.md - 单页思维模型：运行时拓扑、包主干、端到端流程。
- docs/desktop.md - Electron 应用：进程模型、托盘优先 UX、控制中心、安全模型。
- docs/agent-integrations.md - 如何配置 Claude Code、MCP、OpenCode、Cursor 和 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 或代理集成设置付费墙——也永远不会向你出售你可以自己免费制作的内容。

如果你想支持这个项目：给仓库加星，孵化一只宠物，与朋友分享。

安全与隐私

- 仅限本地：OpenPets IPC 使用本地套接字/命名管道工作，并通过每次运行随机生成的安全令牌进行保护。
- 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 提供。