lishLRF/DSH-desktop-pet

DSH 桌面宠物

一个面向 DeepSeek Harness (DSH) 的桌面宠物：
不把 DSH 窗口置顶也能实时看到它的工作状态，任务完成时宠物头顶弹出气泡提醒。
由「一个 DSH 插件」+「一个 Electron 桌面小窗」两部分组成。

#dsh-plugin #electron

功能

| # | 能力 |
| - | ---- |
| 1 | 预设 9 个状态（空闲 / 思考中 / 执行中 / 子代理 / 工作流 / 等待审批 / 已阻塞 / 出错 / 任务完成），在「设置 → 插件 → 插件配置 → 桌面宠物」里为每个状态选择本地图片（绝对路径，留空用内置默认）。 |
| 2 | 状态实时关联 DSH 当前工作内容：agent 运行/空闲、工具执行、子代理、工作流、Goal、审批、错误等，经 WebSocket 推送。 |
| 3 | 开启后常驻桌面：置顶、无边框、透明、可鼠标拖动位置（位置自动记住）。 |
| 4 | 点击宠物即可把 DSH 调到前台（Windows 优先聚焦浏览器，兜底用默认浏览器打开）。 |
| 5 | 任务完成（Goal 完成 / Workflow 结束 / 每次回合结束，均可在设置里开关）时弹出气泡「XXX任务已完成，请注意查看」。 |

架构

浏览器：DSH Web (http://127.0.0.1:3080)
└─ Client 半边：设置卡片（settings.plugin.item）
└─ fetch GET/POST /desktop-pet/config ──┐
▼
DSH Host（Node 进程）
└─ Host 半边：配置文件 ~/.dsh/desktop-pet/config.json（唯一事实源）
· HTTP 路由：GET/POST /desktop-pet/config、GET /desktop-pet/health
· 状态机：订阅 agent/status、tools、subagent、workflow、goal、error 等事件
· WebSocket 路由：/desktop-pet/ws（推送 state + config）
│ ws://127.0.0.1:3080/desktop-pet/ws
▼
Electron 桌面宠物（独立进程）
└─ 无边框透明置顶窗 · WS 客户端(自动重连) · 状态渲染 · 拖动 · 点击调出 DSH · 气泡

协议细节见 docs/protocol.md，设计文档见 docs/specs/2026-08-17-desktop-pet-design.md。

仓库结构

DSH-desktop-pet/
├─ packages/
│  ├─ dsh-plugin/     # DSH 双面插件（Host 状态机 + WS 桥；Client 设置卡片）
│  └─ app/            # Electron 桌面宠物窗口
├─ docs/              # 设计文档 + 协议契约
└─ .github/           # CI 与 Issue/PR 模板

安装与部署

1. 安装 DSH 插件

本插件是标准 DSH bundle（dsh.bundle + dsh.client 声明），用 dsh plugin 装进 web profile：

从 GitHub 安装（推荐；供应链安全建议锁定 commit：#）
dsh plugin --profile web add github:lishLRF/dsh-desktop-pet

或从本地目录 / tarball 安装
dsh plugin --profile web add ./dsh-desktop-pet/packages/dsh-plugin
pnpm pack 后：dsh plugin --profile web add ./dsh-desktop-pet-0.1.0.tgz

pnpm ≥ 10 会拒绝执行 git 依赖的 prepare 构建脚本，第一次 add 会打印需放行的包名，写进
profile 的 pnpm-workspace.yaml 再重跑：
allowBuilds:
dsh-desktop-pet: true

2. 启动桌面宠物窗口

cd packages/app
pnpm install
pnpm dev          # 开发运行（electron .）
或打包：pnpm dist   → 产出安装包到 packages/app/dist/

宠物窗口默认连接 http://127.0.0.1:3080（可在宠物本地配置 ~/.config/DSH Desktop Pet/config.json
或系统对应路径里改 dshUrl）。

跟随 DSH 启动：pnpm dist 打包出可执行文件后，在「设置 → 插件 → 插件配置 → 桌面宠物」里填上该文件路径并开启「跟随启动」；之后 DSH 启动会自动拉起宠物、退出时自动关闭，无需再手动 pnpm dev。

3. 启动 DSH 并验证

dsh web

验证：

1. 「设置 → 插件 → 插件配置」里出现 桌面宠物 卡片。
2. 宠物窗口出现，DSH 工作时宠物状态随之变化。
3. curl http://127.0.0.1:3080/desktop-pet/health 应返回 { ok: true, ... }。
4. 组合检查：dsh --profile web --dump-config，找到 dsh-desktop-pet 这一层即为成功。

卸载

dsh plugin --profile web remove dsh-desktop-pet

环境要求
- Node ≥ 20，pnpm ≥ 10。
- 桌面宠物窗口需要 Electron（应用自带依赖）。

配置

所有配置都在「设置 → 插件 → 插件配置 → 桌面宠物」卡片里：

- 启用开关：关闭后宠物窗口隐藏。
- 状态图片：9 个状态各自一个本地图片绝对路径（SVG/PNG/GIF/WebP），留空使用内置默认。
- 气泡触发：Goal 完成 / Workflow 结束 / 每次回合结束，各自可开关。
- 气泡文案与时长：{name} 会被替换为任务名（goal 目标 / workflow 名 / 会话标题）。
- 跟随启动：填好宠物应用的可执行文件路径并开启开关，DSH 启动时自动拉起宠物、退出时自动关闭（无需手动 pnpm dev）。

配置持久化到 ~/.dsh/desktop-pet/config.json，由 Host 插件独占读写。

开发

pnpm install

插件
pnpm --filter dsh-desktop-pet test        # vitest
pnpm --filter dsh-desktop-pet typecheck   # tsc --noEmit
pnpm --filter dsh-desktop-pet build       # lib/index.js（host）+ lib/client.js（browser）
pnpm --filter dsh-desktop-pet watch       # tsdown --watch

桌面应用
pnpm --filter dsh-desktop-pet-app check   # node --check 语法校验
pnpm --filter dsh-desktop-pet-app dev     # electron .

许可证

MIT —— 见 LICENSE。

已知限制与路线图

- 浏览器无法用原生文件选择器返回绝对路径，v1 的图片路径为手动输入；后续可在宠物右键菜单加原生文件选择器（经 HTTP 回写）。
- 点击调出 DSH 的焦点策略：Windows 优先，macOS/Linux 兜底为 openExternal。
- 宠物默认图片为内置 SVG 占位，便于替换；未内置动画帧/骨骼动画。

贡献

见 CONTRIBUTING.md。欢迎提 issue 与 PR；较大改动请先开 discussion 沟通。