FlytoMAYDAY80/dsh-pet

五种状态预览

DSH 桌宠是一只独立的桌面应用：当你在浏览器、IDE、文档里工作时，鲸鱼始终悬浮在桌面一角，用表情、气泡和音效告诉你——有会话在跑、需要你去审批、任务做完了。把“任务状态”从需要主动查看的页面，变成余光即得的实时信号。

📦 本项目随 DeepSeek Harness 发布而开源（原托管于 dsh-external 组织仓库，现以个人账号仓库作为公开源）。欢迎使用、定制与贡献。

✨ 核心特性

- 离屏状态感知：独立置顶悬浮窗，跨全屏 App 可见，不打开 DSH 也能看见状态
- 人工介入零遗漏：「需要确认」（审批/提问）最高优先级呈现 + 专属音效，不会错过需要你的节点
- 毫秒级实时：双 WebSocket 通道（审批/提问推送 + 运行状态翻转推送），状态变化即时响应
- 跨会话聚合：多会话并行时气泡逐行列出每个会话，数量再多也可滚动查看
- 低打扰：只在状态真正变化时动画/发声，不刷存在感
- 精准点击穿透：仅鲸鱼当前帧的可见像素与可见气泡响应鼠标，其余透明区域不遮挡后方应用
- 对 DSH 零侵入：纯只读 HTTP/WebSocket 接口，不写入任何数据，卸载即消失
- 零代码定制：custom/ 目录一键换图案、配色、音效（见下方“定制”）

📊 五种状态

| 状态 | 鲸鱼表现 | 含义 |
|---|---|---|
| 🔴 需要确认 | 瞪眼 + 眉毛 + o 嘴 + 提示音 | 有审批/提问等你处理 |
| 🔵 工作中 | 专注眼 + 喷水动画 | 有会话正在运行 |
| 🟢 完成待查看 | 开心眯眼 ^^ + 星星 | 任务刚完成，去看结果 |
| 💤 空闲 | 睡觉 + zzz | 无任务，安心休息 |
| 😵 离线 | 灰度 + X 眼 | 连不上 DSH，自动重试 |

优先级：需要确认 > 工作中 > 完成待查看 > 空闲 > 离线。

⬇️ 下载与安装

方式一：下载安装包（推荐） — 从 GitHub Releases 下载：

| 平台 | 安装包 | 说明 |
|---|---|---|
| macOS Apple Silicon | dsh-pet--arm64.dmg | 双击打开，把鲸鱼拖入 Applications |
| macOS Apple Silicon | dsh-pet--arm64-mac.zip | 便携版，解压即用；删文件夹即卸载 |

方式二：从源码运行 — 需要 Node.js 18+ 与 pnpm：

pnpm install   # 安装依赖（Electron）
pnpm start     # 启动桌宠（默认右下角）

可选：DSH_PET_URL=http://127.0.0.1:3080 指定 DSH GUI 地址（默认 3080）。

🖱️ 使用

| 操作 | 行为 |
|---|---|
| 单击鲸鱼/气泡 | 打开 DSH GUI（系统浏览器，可切换桌宠窗口直达会话） |
| 按住拖拽 | 移动位置 |
| 右键鲸鱼/气泡（或托盘图标） | 菜单：气泡开关、音效开关、大小调节、打开方式 |
| 滚轮（气泡内） | 滚动查看多会话列表 |

🎨 定制（零代码）

把文件放进 custom/ 目录，重启即生效：

custom/
├── sprites.json      ← 像素图案 + 配色（可用脚本从参考图生成）
├── attention.m4a     ← 「需要确认」音效
└── done.m4a          ← 「任务完成」音效

从参考图生成图案：

python3 scripts/ref_to_sprites.py

详细格式见 custom/README.md 与 产品说明.md。

❓ 常见问题

Q：桌宠没出现在桌面上？
先确认 DSH GUI 已在 http://127.0.0.1:3080 运行；桌宠离线状态（灰度 X 眼）会自动重试连接。

Q：听不到提示音？
右键鲸鱼 → 菜单里打开“音效”，并确认系统音量；「需要确认」与「任务完成」各有专属音效。

Q：桌宠会不会把数据传到云端？
不会。桌宠只读取本地 DSH 接口（HTTP/WebSocket），无任何云端上报，卸载即消失。

🛠️ 开发与自检

pnpm smoke        # 状态引擎冒烟测试（连接/轮询/WebSocket/状态推导）
pnpm shot         # 两种皮肤 × 5 状态截图到 .shots/
pnpm hittest      # 透明区、鲸鱼像素、气泡显隐与换帧热区回归测试
python3 scripts/verify_pixel_src.py   # 素材规格与参考图一致性校验python3 scripts/gen_icon.py           # 重新生成应用图标

📁 目录结构

main.js          主进程：窗口/托盘 + DSH 状态引擎（轮询 + 双 WebSocket）+ 素材包加载
preload.js       contextBridge IPC
app/             渲染层：index.html + styles.css + renderer.js + 像素素材 + 音效
custom/          自定义素材包（用户定制入口）
pixel-src-hd/    像素素材源（JSON + PNG）
scripts/         生成/自检脚本
docs/            截图与演示素材

📄 License

MIT © FlytoMAYDAY80

免责声明

本仓库是独立的第三方工具，与 DeepSeek / DeepSeek AI 官方无关。DeepSeek Harness（dsh）是官方项目（MIT）。鲸鱼形象与"DeepSeek"名称用于指代所对接的官方产品，版权归其各自所有者。

English

A floating desktop whale for DeepSeek Harness — know your session status at a glance without opening the DSH page.

DSH 桌宠 (dsh-pet) 是一款独立的桌面应用：一只小鲸鱼漂浮在屏幕角落，通过表情、气泡和音效反映你的 DSH 会话状态——需要你批准 / 工作中 / 已完成 / 空闲 / 离线。

- 下载：GitHub Releases（macOS Apple Silicon，DMG 或 ZIP）
- 从源码运行：pnpm install && pnpm start（Node.js 18+，pnpm）
- 自定义：将你自己的精灵图/颜色/音效放入 custom/，重启即可生效
- 隐私：仅读取本地 DSH HTTP/WebSocket 接口，无云端上传
- License：MIT

DSH 桌宠只读取本地 DSH 接口，无任何云端上报。