@epiphanye/pi-hud · Rana 桌面宠物

让 Pi Coding Agent 的状态以常驻桌面的 Rana 桌宠呈现：透明角色动画、状态气泡、桌面置顶与可拖动位置。它是标准 Pi Package：TypeScript 扩展负责接收 Pi 生命周期事件；Python / PySide6 客户端负责显示原生桌宠。

安装

先安装 PySide6：

# Windows / WSL2：安装到 Windows 原生 Python
py -3 -m pip install PySide6

# Linux 桌面
python3 -m pip install --user PySide6

安装已发布版本：

pi install npm:@epiphanye/pi-hud

本地使用此工程：

pi install /home/epiphanye/dev/floating-status-hud

重启 Pi 或执行 /reload 后生效。请删除旧的手工扩展，避免争用 HUD 端口：

rm -f ~/.pi/agent/extensions/hud.ts ~/.pi/agent/extensions/hud_client_windows.py

平台

Pi 运行环境	桌宠窗口
WSL2 Ubuntu	Windows 原生 Python / Win32 Topmost
Windows	Windows 原生 Python
Linux 桌面	Linux Python / PySide6

在 WSL2 中即使启用 WSLg，也优先创建 Windows 原生窗口，以覆盖普通 Windows 应用。

状态与动作

Rana 使用随包提供的精灵图动画。每种状态会持续循环，直到 Pi 事件或命令改变状态。

Pi 状态	Rana 动作行	气泡
空闲	第 1 或第 7 行（进入时随机，之后保持该循环）	默认一直显示
思考与执行中	第 9 行	默认一直显示
目标达成	第 4 行	默认一直显示，随后 Pi 自动回到空闲
执行出错	第 6 行	默认一直显示
等待用户确认	第 8 行	默认一直显示
向右拖动	第 2 行	默认一直显示
向左拖动	第 3 行	默认一直显示
上下拖动	第 5 行	默认一直显示

精灵图按固定 8×9 格子切帧（1536×1872，单格 192×208）。帧数不足 8 的行只播放左侧有效帧，不按整行宽度重新均分。空闲、完成和错误动作约为 3 FPS；工作、等待确认和拖动动作约为 4 FPS。

默认角色高度约为 160px。气泡根据当前状态文字自适应宽度并位于角色正上方；超长文字会省略。气泡与角色一起常驻并等比缩放，只有右键“隐藏气泡”才会关闭。桌宠位置、气泡偏好和大小保存在：

~/.pi/hud-pet.json

旧版 ~/.pi/hud-position.json 的位置会在首次运行时迁移。

命令

/hud             # 显示 / 隐藏桌宠
/hud show        # 显示桌宠
/hud hide        # 隐藏桌宠
/hud restart     # 重启 HUD 服务与桌宠
/hud waiting     # 显式进入“等待用户确认”状态
/hud idle        # 立即回到空闲状态
/hud status      # 显示端口、心跳、素材和当前动画诊断

等待确认不通过猜测 Agent 文本触发：当需要时使用 /hud waiting；确认完成后使用 /hud idle，或继续让 Pi 执行下一轮任务。

操作

• 左键拖动：角色可见轮廓和气泡可拖动，外围透明区域会将点击传递给下层窗口。向右、向左、上下分别播放第 2、3、5 行；同方向移动连续播放，中途改变方向才切换动作。轻微点击不会开始拖动，松开后记住位置并恢复当前 Pi 状态动作。
• Ctrl + 滚轮：按约 16px 步进缩放角色高度（80–320px）；气泡、文字和精确点击热区一起缩放。右键“大小”可选小 / 默认 / 大 / 重置。
• 左键双击（Windows / WSL）：恢复启动桌宠前处于前台的 Edge、Windows Terminal 或 VS Code 宿主窗口；若窗口最小化会先恢复。
• 右键菜单：显示/隐藏气泡、查看当前状态与动画帧、调整大小、重新置顶、隐藏桌宠或退出桌宠。
• 退出桌宠只关闭图形窗口，不停止 Pi 服务；健康检查会尝试重新拉起客户端，也可使用 /hud restart。
• /hud restart 会先等待旧连接、TCP 端口和 Windows 单实例锁释放，再重新拉起客户端，因此可能有约 1 秒的短暂延迟；可用 /hud status 查看 phase、端口、最近启动和具体错误。

Windows 只能稳定恢复 Edge、VS Code 或终端的顶层窗口，不能可靠定位 http://127.0.0.1:30141/ 的特定 Edge 标签页，也不能选择具体 Terminal / VS Code 终端标签。

生命周期与限制

• Pi CLI、Pi Web 服务、会话切换或 /reload 正常结束时，桌宠会立即关闭。
• 关闭单个 Pi Web 浏览器页面不等于停止 Pi Web 后端服务，因此桌宠会保留到服务停止。
• Pi 被强制终止、WSL 被关闭或本地通信中断时，桌宠约 12 秒收不到有效服务端消息后自动退出。
• Windows 使用单实例互斥锁，重复启动不会叠加多个桌宠。
• 桌宠会定期重新申请 Windows Topmost；无边框窗口化和窗口化全屏游戏通常可恢复显示。

独占全屏游戏、UAC 安全桌面、锁屏、受保护内容和不同管理员权限级别由 Windows 管理，普通桌面程序无法保证置顶或激活窗口。

诊断

在 Pi 中执行：

/hud status

输出会包含重启阶段、端口绑定、最近启动与错误、客户端心跳、素材状态，以及当前 clip、精灵图行/帧、实际 FPS、气泡和缩放诊断。

WSL 中可验证 Windows Python 启动器：

/mnt/c/Windows/pyw.exe -3 --version

若启动器不在默认位置，在启动 Pi 前设置：

export PI_HUD_PYW="/mnt/c/Windows/pyw.exe"
pi