Petdex Win 桌面 AI 宠物
把 AI 编程助手和自动化工具的运行状态转化成可视化、可交互的 Windows 桌面宠物，并支持聊天与语音对话。
ElectronNode.jsWebSocketClaude Code HooksOpenAI-compatible APIDashScope ASR / TTS
产品介绍
Petdex Win 是一个基于 Electron 的 Windows 桌面宠物应用。它把 AI 编程助手或其他自动化工具的工作状态变成桌面上看得见、听得到、可以互动的宠物反馈，让用户不必一直盯着终端，也能快速知道当前任务处于运行、等待、完成还是失败状态。
核心体验
让 AI 助手的运行过程从一段不可见的终端日志，变成一个有动作、有气泡、有声音并且可以对话的桌面伙伴。
当前项目属于功能链路基本完成的开发原型，尚未完成开箱即用的默认宠物、完整配置面板、Windows Hook 稳定性验证、自动化测试和 Windows 安装包。语音能力依赖外部 API、网络和麦克风权限，API Key 需要避免明文暴露。
解决方案
| 问题 | 当前解决方案 |
|---|---|
| 终端状态反馈不直观 | 通过 Sidecar 接收状态并映射为宠物动画和气泡，让运行、思考、等待、完成和失败在桌面上可见。 |
| 不同 Agent 缺少统一状态入口 | 提供本地 HTTP 状态接口和 Claude Code Hooks，同时预留其他 Agent 或脚本通过接口调用。 |
| 桌面应用缺少个性和陪伴感 | 使用可发现、可切换的宠物资源、persona.md、独立音效、语音和聊天历史打造不同角色。 |
| 用户需要频繁切换窗口才能沟通 | 双击宠物打开聊天窗口，支持 OpenAI-compatible LLM、SSE 流式回复和按宠物保存聊天记录。 |
| 语音交互容易出现回声和状态混乱 | 提供按住说话和持续对话两种模式，播放 TTS 时暂时抑制麦克风输入，降低自激回声。 |
Agent 执行任务→Hook 或 HTTP 上报状态→Sidecar 鉴权与排队→Electron 更新宠物动画→气泡与音效反馈→聊天或语音互动→保存角色状态与聊天记录
产品功能
01 · 桌面宠物窗口
- 透明无边框窗口
- 始终置顶且不占任务栏
- 左键拖拽和屏幕边界限制
- 系统托盘驻留、显示/隐藏和退出
- 聊天窗口跟随宠物位置移动
02 · 精灵动画系统
- 支持 8×9、72 帧精灵图集
- idle、running、running-left、running-right
- waving、jumping、failed、waiting、review
- 随机动作、动画循环、速度调整和状态持续时间
- 拖拽方向同步切换左右奔跑动画
03 · Agent 状态联动
- Sidecar 提供 /health、/state、/bubble 等接口
- token 鉴权、状态白名单、请求体和频率限制
- 状态队列、重复状态合并和节流
- Claude Code PreToolUse、PostToolUse、Stop 和 Notification Hooks
- 兼容其他 Agent 或脚本通过 HTTP 写入状态
04 · 聊天与人格
- 文本聊天和 SSE 流式回复
- OpenAI-compatible API，可接入 OpenAI、DeepSeek 等服务
- 每个宠物独立 persona.md 和聊天历史
- 宠物切换后自动切换对应记录
- 支持清空聊天和隐藏窗口而不是销毁
05 · 语音与音效
- 按住麦克风说话，松开后调用 ASR
- DashScope Fun-ASR 实时语音识别
- CosyVoice TTS 语音合成和回答播放
- 持续对话模式与 WebSocket ASR
- 跑步、跳跃、挥手、失败音效和 Web Audio 兜底
06 · 宠物资源系统
- 从项目目录、%USERPROFILE%\.codex\pets 和 %USERPROFILE%\.petdex\pets 发现资源
- 至少需要 spritesheet.webp 或 spritesheet.png
- 支持 pet.json、persona.md、run/jump/wave/fail.mp3
- 不同宠物可拥有不同人格、语音、语速和音效
- 支持切换皮肤和调整动画速度、音量
使用方法
Petdex Win 是 Windows Electron 应用。准备好宠物资源后安装依赖并启动应用，再通过 Claude Code Hooks、命令行工具或 HTTP 接口触发宠物状态。
示例指令
在项目目录执行 npm install，然后运行 npm run up 或 npm start；安装 Claude Code Hooks 使用 npm run hooks -- install。
- 在项目目录安装 Electron 和 ws 依赖。
- 把宠物资源放进 %USERPROFILE%\.petdex\pets\<宠物 slug>\，至少提供一张 8×9 精灵图。
- 运行 npm run up 启动 Electron 桌面宠物和本地 Sidecar 服务。
- 运行 npm run hooks -- install，把 Claude Code 事件映射到宠物状态。
- 也可以使用 node bin/petdex-win.js state running、waiting、waving 等命令手动触发状态。
- 双击宠物打开聊天窗口；配置 LLM 后可以进行文本聊天，配置 DashScope 后可以使用语音交互。
- 通过 node bin/petdex-win.js status、toggle 和 down 查看、切换或关闭应用。
其他使用方式
- LLM 配置位于 %USERPROFILE%\.petdex\config.json，支持 OpenAI-compatible baseUrl、apiKey 和 model。
- 每个宠物可以通过 pet.json 配置自己的 TTS model、voice 和语速。
- 如果没有音频资源，程序会使用 Web Audio API 生成基础提示音；如果没有 API Key，文本和桌面状态链路仍可独立调试。
当前开发状态
项目已经打通“Agent/Hook—本地 Sidecar—Electron 宠物—动画、气泡、音效”的核心链路，也具备文本聊天、人格加载、聊天记录和语音交互能力，目前处于开发原型到可发布产品之间。
| 模块 | 当前状态 |
|---|---|
| Electron 桌面窗口与系统托盘 | 已完成：透明无边框、置顶、拖拽、边界限制和显示/隐藏 |
| 宠物发现、切换与精灵动画 | 已完成：资源发现、8×9 图集、状态动画、方向和速度控制 |
| Sidecar HTTP 服务 | 已完成：:7777、状态/气泡接口、token 鉴权、队列和节流 |
| Claude Code Hooks | 已完成基础实现：工具调用、思考、完成和等待状态映射；Windows 兼容性仍需实测 |
| LLM 流式聊天与宠物人格 | 已完成：OpenAI-compatible 接口、SSE、persona.md 和按宠物聊天记录 |
| ASR、TTS 和持续对话 | 已接入：DashScope Fun-ASR、CosyVoice 和 WebSocket；依赖外部服务与权限 |
| 仓库内默认宠物 | 未完成：assets/pets 为空，全新环境需要用户级宠物资源才能启动 |
| 配置面板与密钥保护 | 未完成：当前可能需要手动编辑 config.json，API Key 仍需避免明文保存 |
| 自动化测试与 API 测试 | 未完成：目前主要是手动调试脚本，缺少 Sidecar、Hook、动画、聊天和语音测试套件 |
| 安装包与发布流程 | 未完成：尚未接入 electron-builder/forge、Windows EXE、自动更新和正式发布脚本 |