瓦力桌宠 DDUP111/walle-desktop-pet

瓦力桌宠（WALL·E Desktop Pet）

用 Electron + HTML/CSS/JavaScript 做成的 Windows 桌面宠物，同时作为 DeepSeek Harness 的物理状态指示灯。

仓库内附带一个 Harness 生命周期插件 @local/walle-desktop-pet： Harness 启动时自动拉起瓦力，Harness 退出或插件卸载时自动关闭瓦力。
本机已经安装并启用。

瓦力桌宠预览

预览图中的蓝色渐变仅用于展示透明窗口效果，程序实际背景完全透明。

功能

- 随 Harness 自动启动、随 Harness 退出自动关闭
- 无边框、全透明、始终置顶、任务栏隐藏
- 透明区域点击穿透，只有瓦力图片区域拦截鼠标
- 按住左键拖动瓦力
- 右键播放 ./assets/walle.mp3
- 双击瓦力，通过主进程的 child_process.spawn 打开 DeepSeek Harness
- 按住鼠标中键约 1.2 秒退出程序（显示进度条）
- 实时读取 Harness 本地状态，驱动 idle / busy / done 动画
- 瓦力图片宽度约 120px，保持比例

Harness 状态联动

| 状态 | 触发条件 | 表现 |
| idle | 没有进行中的任务，且日志没有新写入 | 轻微上下浮动 |
| busy | 有进行中的 turn / step，或日志目录刚有新写入 | 高频抖动、变亮、提高饱和度 |
| done | 任务从进行中变为结束，且最终回复非空 | 向上跳跃、金色光晕、播放 walle.mp3，播放完自动回到 idle |

监听了什么

默认监听用户目录下的 .dsh：

%USERPROFILE%\.dsh

具体使用两类文件：

.dsh\sessions\\session.v4.jsonl.zstd
.dsh\storages\session_projcache\sessions\.json

- 会话 .jsonl.zstd 是压缩日志，用于监听文件写入活动和日志文件数量。
- 明文 session_projcache\sessions\.json 用来读取 turnBoundary.openTurnStartSeq 和 sessionStats.openStep：有值表示任务正在运行。
- 当这两个标记清空，并且最后一条回复内容非空时，判定为 done。
实际日志中对应的完成事件是 turn/end 且 reason.kind 为 completed。

监听使用 fs.watch + 300ms 轮询兜底，避免 Windows 文件原子写入造成漏事件。
monitor.js 是独立可运行的 Node.js 后台脚本，不依赖任何新增 npm 包。

如果 .dsh 不在默认位置

程序会用 os.homedir() 拼接 .dsh。也可以显式指定：

$env:DSH_HOME = "D:\另一处\.dsh"
npm start

单独调试状态监听

npm run monitor

终端会实时输出类似：

[HarnessMonitor] BUSY (active-turn) active=1 files=2
[HarnessMonitor] DONE (turn-completed)
[HarnessMonitor] IDLE (no-active-turn)

文件结构

desktop pet/
├─ package.json
├─ package-lock.json
├─ main.js # 窗口、穿透、拖拽、启动 Harness、状态 IPC ├─ monitor.js # Node.js 后台状态监听脚本 ├─ preload.js # contextBridge 安全桥接 ├─ index.html # 引入瓦力图片 ├─ style.css # 透明窗口、状态动画 ├─ renderer.js # 鼠标交互、音频、状态表现 ├─ preview.png # 预览图 ├─ harness-plugin/ # 随 Harness 启停的本地 Host 插件 │ ├─ index.js │ ├─ cordis.patch.yml │ ├─ package.json │ ├─ locale/ │ └─ icon.svg └─ assets/ ├─ walle.png # 瓦力透明背景图片（已裁剪多余透明留白） └─ walle.mp3 # 瓦力叫声

启动方式（自动）

插件已经安装在当前 desktop profile 并启用。现在直接：

1. 正常打开 DeepSeek Harness。
2. 瓦力会自动启动。
3. 关闭 Harness，瓦力会自动退出。

不需要再执行 npm start。 手动再启动一份会与插件启动的实例冲突。

插件信息：

包名：@local/walle-desktop-pet 目录：harness-plugin/

它在 Harness 的 apply() 生命周期里用 child_process.spawn 启动 Electron，在插件 dispose 时通过 taskkill /PID <pid> /T /F 结束整个桌宠进程树。
桌宠自己还会每 1.5 秒检查一次 Harness 父进程，父进程消失时自动退出，作为崩溃兜底。

插件用 link 方式安装在 Harness profile 中。如果以后移动了项目目录，需要在 Harness 插件管理里重新安装一次 harness-plugin。
其他用户可以在 Harness 插件管理里安装本地目录 harness-plugin。

临时禁用自动启动

在 Harness 的插件/扩展管理里停用 瓦力桌面状态宠物 （@local/walle-desktop-pet）即可；重新启用会再次自动拉起桌宠。

手动开发启动

调试桌宠代码时，可以先停用上面的插件，再执行：

cd "<项目目录>"
npm install
npm start

或者从 GitHub 克隆：

bash
git clone https://github.com/DDUP111/walle-desktop-pet.git
cd walle-desktop-pet
npm install
npm start

如果 PowerShell 拦截 npm.ps1： powershell npm.cmd install npm.cmd start

操作

| 操作 | 效果 |
| 按住左键拖动 | 移动瓦力 |
| 左键双击瓦力 | 打开 Harness 桌面客户端 |
| 右键单击瓦力 | 播放 walle.mp3 |
| 按住鼠标中键约 1.2 秒 | 退出桌宠（底部有进度条） |
| 鼠标移到透明区域 | 点击穿透到桌面 |

如果鼠标没有中键，也可以先单击瓦力让窗口获得焦点，然后按 Alt + F4 退出。

Harness 客户端路径

双击瓦力打开 Harness 时，main.js 会按顺序查找以下路径： text %HARNESS_PATH% D:\DeepSeek Harness\DeepSeek Harness.exe %LOCALAPPDATA%\Programs\DeepSeek Harness\DeepSeek Harness.exe %ProgramFiles%\DeepSeek Harness\DeepSeek Harness.exe

也可以显式指定： powershell $env:HARNESS_PATH = "D:\新目录\DeepSeek Harness.exe"
npm start

如果客户端换了位置，修改 main.js 里的 HARNESS_CANDIDATES，或者设置 HARNESS_PATH 环境变量。检查路径： powershell Test-Path "D:\DeepSeek Harness\DeepSeek Harness.exe"

音频与图片

音频使用相对路径： js const AUDIO_SRC = './assets/walle.mp3';

图片用普通 引入，CSS 宽度 120px： html

原 PNG 四周有大量透明留白，已经裁掉，只保留约 4px 透明边距，因此 120px 显示出来就是完整瓦力。

为了在没有「月牙眼」素材的情况下表现忙碌，程序主要用 CSS 的
brightness()、saturate()、contrast() 和抖动动画模拟状态。

常见问题

Electron 下载慢或卡住 powershell $env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
npm install
npm start

npm start 后立即结束，没有窗口
powershell
$env:ELECTRON_RUN_AS_NODE

如果有输出，先清理再启动： powershell Remove-Item Env:ELECTRON_RUN_AS_NODE
npm start

状态一直不变

先运行 npm run monitor 看监听脚本是否能读到 .dsh：

- 一直输出 IDLE (waiting-for-dsh)：DSH_HOME 路径不对。
- 输出 BUSY 但桌宠不动：检查桌宠终端里的 [WALL·E] Harness 状态 日志。
- Harness 升级后内部缓存字段若变化，需要同步调整 monitor.js 里的 openTurnStartSeq、openStep 和 turnOutline 读取逻辑。

打开 Harness 后瓦力没有自动出现

1. 在 Harness 的插件管理里确认「瓦力桌面状态宠物」处于启用状态。
2. 确认 <项目目录>\node_modules\electron\dist\electron.exe 存在。
3. 如果移动过项目目录，请重新安装本地插件。
4. 如果手动 npm start 的实例还在，先通过鼠标中键退出它，再重启 Harness。

关闭 Harness 后瓦力还留着

正常情况下插件 dispose 会结束桌宠。若 Harness 是异常崩溃退出，桌宠会在约 1.5 秒内发现父进程消失并自行退出；如果仍然没有退出，可以按住鼠标中键 1.2 秒手动关闭。

安全设置

- contextIsolation: true
- nodeIntegration: false
- sandbox: true
- 只通过 preload.js 暴露少量 IPC 动作
- 禁止页面导航和新窗口

License

代码以 MIT License 开源，Copyright (c) 2026 DDUP111。

assets/walle.png 与 assets/walle.mp3 是项目使用者提供的角色素材，不属于 MIT 许可范围。WALL·E 角色及相关商标归 Disney / Pixar 所有，本项目是非官方粉丝作品，仅用于个人学习与演示，请勿用于商业用途。
如果你要再分发这些素材，请先确认你拥有相应权利。