# openpets

> Automatically syncs with a desktop pet while the DSH coding agent runs, displaying reaction bubbles for thinking, completed, error, or awaiting approval based on the agent's working status.

## Metadata

- Author: [@alvinunreal](https://github.com/alvinunreal)
- Repo: <https://github.com/alvinunreal/openpets.git>
- GitHub: [alvinunreal/openpets](https://github.com/alvinunreal/openpets)
- Stars: 1,091
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://openpets.dev>
- Topics: `ai-agents`, `claude-code`, `coding-agents`, `desktop-companion`, `desktop-pet`, `dsh-plugin`, `electron`, `mcp`, `opencode`, `openpets`, `plugin-sdk`, `plugins`, `typescript`
- Forks: 95
- Open Issues: 13
- Last push: 2026-08-18T18:00:52.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:alvinunreal/openpets/packages/dsh
```

## Wiki

## 一句话定位
把 OpenPets 桌面宠物接入 DSH 编码代理：根据代理当前是在思考、报错还是等待审批，自动让宠物显示对应的反应气泡和短句提醒，把编码过程可视化但不会泄露任何业务数据。

## 核心能力
- 监听 DSH 的 `agent/status` 事件，把代理进入"思考中"映射为 thinking 反应，"已完成"映射为 success 反应
- 监听 DSH 的 `agent/error` 事件，让宠物立刻切换到 error 反应并弹出报错提示短句
- 监听 DSH 的 `approval/request` 事件，把等待用户审批的状态映射为 waiting 反应，提示"需要批准"
- 自动派发使用本地 IPC、500 毫秒超时的客户端，不走远程通道，忽略远程环境变量
- 内部采用预置短句池加校验，避免把代码、URL、路径或密钥混入气泡文案
- 在错误事件后的 5 秒内抑制 success/idle 反应，避免"刚报错立刻显示完成"的视觉混乱

## 技术实现
- **语言**: TypeScript（ESM，包内编译产物为 `dist/`）
- **关键依赖**: `@deepseek-ai/cordis`（peerDep）、`@open-pets/agent-events`（预置短句池与校验）、`@open-pets/client`（本地 IPC 客户端）
- **架构模式**: 通过 `dsh.bundle.patch` 把 `openpets-dsh` 这个 Cordis 插入 `apply(ctx, options)` 注册到宿主上下文的 `agent/status`、`agent/error`、`approval/request` 三个事件钩子上；分类器只读事件分类值，由调度器异步派发，绝不阻塞宿主流程
- **入口文件**: `packages/dsh/src/index.ts`（导出 `apply`、`name` 等，由 `cordis.patch.yml` 加载）

## 适用场景
- DSH 用户希望让桌面宠物反映出编码代理此刻的工作状态（思考、报错、等待审批），获得更直观的"陪伴感"，而不希望任何代码或提示词被外泄。
- 不需要远程宠物控制、不希望通过 MCP 调用模型工具的轻度 DSH 用户，需要一个开箱即用、严格本地的轻量集成。
- 想给不同 DSH profile 单独启用宠物联动，并保持与其他 OpenPets 插件/远程 MCP 配置完全解耦的场景。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| `@deepseek-ai/cordis` | ^4.0.1 | 包以 peerDependencies 形式声明，DSH 宿主需自带此核心库 |
| `@open-pets/agent-events` | workspace | 提供事件分类用预置短句池与气泡文本校验 |
| `@open-pets/client` | workspace | 提供本地 IPC 客户端能力 |
| 操作系统 | 未声明 | 客户端内部通过 `@open-pets/client` 走本地 IPC，可跨平台运行 |

源码中未声明 Node 最低版本，亦未声明平台限制。

## 安装方式
```bash
dsh plugin --profile web add github:alvinunreal/openpets/packages/dsh
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 本插件无需额外配置 | — | 通过 `dsh plugin --profile web add` 安装即生效；`OpenPetsDshOptions` 字段（`clientFactory`/`schedule`/`random`/`now`）仅供宿主测试注入 | — |

## 常见问题
**Q: 这个插件会被安装到 DSH 的哪里？**

A: 通过 `dsh plugin --profile web add` 按指定的 profile 安装；要让多个 profile 都启用，就对每个 profile 分别执行同一命令。

**Q: 启用后我的代码或提示词会被发给宠物吗？**

A: 不会。分类器只读取事件信封里的 `status` 分类值，并且气泡文案只从 `agent-events` 里预先写好的短句池里抽一句；消息会被强制校验，不能包含 URL、文件路径、密钥等敏感内容，也不会转发任何 prompt 或 tool result。

**Q: 它和 OpenPets 自带的远程 MCP 有什么关系？**

A: 本插件完全本地化，使用 500 毫秒超时的本地 IPC 客户端与桌面应用通信，并在测试用例里明确忽略 `OPENPETS_REMOTE_ENDPOINT/TOKEN` 环境变量；远程 MCP 仍可独立配置，互不干扰。

**Q: 宠物反应会卡住 DSH 吗？**

A: 不会。所有分类与派发都是异步、被调度器（默认走 `Promise.resolve().then`）放到事件循环里执行，并由宿主测试可注入的 `schedule` 替换；派发异常会被静默吃掉，绝不回传到 DSH 主流程。

**Q: 报错后宠物要过几秒才显示"完成"，是 bug 吗？**

A: 属于有意为之。源码常量 `errorSuccessSuppressionMs = 5_000` 会在 5 秒内抑制 success/idle 反应，让错误状态先被看见；如果不想等，可以临时关闭后端、等待、或联系作者调整阈值。

**Q: 如何卸载？**

A: 使用对应 profile 的 DSH bundle 移除命令即可；插件不会写入持久化文件，删除后立即失效。

## 上手难度
入门 — 安装命令一行即可启用，且不依赖任何外部服务、远程凭证或额外配置项，DSH 启动后宠物会自动随代理状态切换反应。

## 已知问题与限制
- 暂未发现源码中标注的 TODO/FIXME/已知缺陷；`runtime.test.ts` 已覆盖分类映射、抑制窗口与远程变量忽略三条核心路径。
- 行为上的固有限制（属设计而非 bug）：
  - error 反应后 5 秒内的 success/idle 会被静默抑制，体感上会有"延迟"。
  - 仅支持预置的 4 类（thinking/success/error/permission）短句，无法自定义气泡文案。
  - 仅识别 `agent/status`、`agent/error`、`approval/request` 三类事件，其它 DSH 事件会被分类器直接忽略。
  - 强制使用本地 IPC；若用户配置了远程 OpenPets 端点，此插件也会忽略，仅靠其他插件/CLI 处理远程通道。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [openpets](https://deepseek-plugin.org/plugins/alvinunreal/openpets/packages/dsh)
Wiki generated by AI (model: `MiniMax-M3`)