桌面宠物anyuinlara-bit/dsh-BFF-pet

dsh-BFF-pet 🐾

一只住在 Windows 桌面上的 DeepSeek Harness（DSH）桌宠插件
一个运行在 Windows 上的 DeepSeek Harness 桌面宠物插件，由真实 agent 状态驱动。

透明悬浮窗 + WebM 动画，通过 DSH 的 webServer 状态端点实时反映 Agent 的工作状态。整个插件与 DSH 共生：由 DSH 自动拉起，无独立应用入口、无需额外端口（仅复用 DSH 自身的 127.0.0.1:3080）。

✨ 功能特性

- 透明悬浮桌宠：只在桌面显示宠物本身，无背景块；置顶显示，可任意拖拽
- Agent 状态驱动：空闲 / 思考中 / 工作中（区分搜索/编辑/测试/命令）/ 等待确认 / 完成 / 错误 实时切换动画与气泡
- 状态气泡：在宠物上方显示当前状态文字（如「工作中 · 搜索」）
- 彩蛋调度：空闲随机彩蛋、早/中/晚餐时间彩蛋、长时间工作吃 Token
- 互动：点击触发互动动画，拖拽反馈悬空动画
- 系统托盘 + 右键菜单：触发彩蛋 / 显示隐藏 / 气泡开关 / 透明度 / 大小缩放 / 复位位置 / 退出
- 健壮性：断连检测（DSH 失联自动显示「未连接」并在恢复后回到真实状态）、错误可视化、状态回落（任务完成无活动自动回空闲）

🎬 效果演示

动画由 Agent 实时状态驱动——当 DSH 的 agent 接触信息、执行任务时，桌宠会播放对应的动画。以下是几个代表性场景：

| 工作中 · 搜索 | 完成任务 | 吃 Token |
|---|---|---|
| 工作中·搜索 | 完成任务 | 吃Token |

动画素材来自 dsh-pet（见下方致谢），完整 50+ 个动画随桌宠运行自动触发。

🔄 数据流（逻辑结构）

桌宠的核心是一条从 DSH 到桌宠的单向状态流 + 一条反向的控制流，全部通过 DSH 自身的 webServer 完成，不引入额外通道。

DSH 侧（插件）                          Windows Electron 侧
───────────                            ────────────────────
Agent 产生事件                          桌宠窗口（透明 + 动画）
│                                        ▲
▼                                        │ ipc/webContents 转发
状态机推导（reducer）                        │
│                                        │
▼                                        │
状态端点暴露（GET /state）  ──轮询(1s)──▶  轮询器 → 渲染层 → 播放动画/气泡
│
▼
控制端点（POST /quit）  ◀──退出请求──── 托盘/右键菜单

1. 状态流（正向）：DSH 的 Agent 产生 session/event → 插件内状态机（reducer）把事件推导成宠物状态（空闲/思考/工作/等待/完成/错误）→ 通过状态端点 GET /state 暴露。Windows Electron 每秒轮询该端点，去重后转发给渲染层，驱动动画与气泡切换。
2. 控制流（反向）：托盘/右键菜单的用户动作（触发彩蛋、气泡开关、退出等）→ 渲染层处理，或通过控制端点 POST /quit 通知 DSH 彻底停止。

两条流都只复用 DSH 自身的 127.0.0.1:3080，插件与 DSH 共生，无独立入口、无额外端口。

🖥️ 环境与 Electron 运行时

桌宠是 Windows 原生应用（透明置顶窗口 + 系统托盘）。运行需要 Electron 运行时，程序启动时会自动探测并匹配本机可用的 Electron 路径（无需手动配置），按以下顺序定位：

1. 环境变量 ELECTRON_PATH 显式指定
2. 纯 Windows：node_modules/electron/dist/electron.exe（本项目目录 npm install electron 所得）
3. 兼容：bin/win32-x64/electron.exe

拉取/安装 Electron 由使用者按自身环境执行（例如 Windows 用户先 npm install electron），程序只负责"找到并配对路径"，不打包、不强制任何方式。

- 纯 Windows：DSH 与桌宠同机运行，程序直接启动 Electron 窗口；runtime 就在本地目录，无需跨盘同步。
- WSL2：DSH 在 WSL（Linux），桌宠窗口在 Windows。helper 自动把 runtime 与 bin/ 中的 Windows 版 Electron 同步到 C:\Users\\AppData\Local\dsh-BFF-pet\ 后启动。
注意：WSL 下 npm install electron 拉取的是 Linux 版，无法驱动 Windows 桌宠；WSL 用户需放置 Windows 版 electron 于 bin/win32-x64/（或由 Agent 按环境处理）。

测试与 CI

- 契约测试：npm test（Node 内置 node --test），覆盖 reducer 状态机 + helper 平台路径识别
- 冒烟测试：npm run smoke（syntax 检查所有 src/runtime JS + 契约测试）
- CI：GitHub Actions 每次 push/PR 到 main 自动跑冒烟测试（.github/workflows/ci.yml）

npm test          # 跑 reducer + helper 契约测试
npm test:helper   # 只跑 helper 平台路径测试
npm run smoke     # 冒烟测试（语法 + 契约）

🙏 致谢 / Credits

本项目参考并借鉴了以下优秀的 DSH 桌宠插件，在此致谢：

- dsh-pet — by PC2005-cloud，MIT License。本项目的 50+ 个 WebM 动画素材即来自 dsh-pet（经本地重命名为英文文件名后使用），感谢其精美的动画资产。
- dsh-dafeiyu — by QCYTSN，MIT License。参考其 WSL→Windows helper 桥接、状态机（reducer）与 webServer 端点设计。

注意：本项目的架构与代码为独立实现；动画素材复用自 dsh-pet。两个参考项目均为 MIT License，使用需遵循各自的许可条款（保留版权声明）。

📄 License

MIT