dfzjb/whalemaid-desktop-pet

🐋 像素桌宠 (Pixel Desktop Pet)

像素风蓝发鲸鱼女仆桌面宠物 · DSH Agent 桌面入口

Electron
TypeScript
License
Platform
DSH

📖 项目简介

像素桌宠是一只常驻桌面的像素风蓝发鲸鱼女仆 Q 版宠物，基于 Electron + TypeScript 构建。她不仅是一个会动、会互动的桌面陪伴角色，更是 DSH（DeepSeek Harness）Agent 的桌面入口——将 AI Agent 的状态、任务、审批联动实时可视化到桌宠的表情和动作上。

主要作用

1. 桌面陪伴：36 种动画状态、44 种触发器，小鲸会根据你的操作（点击、拖拽、边缘吸附、定时提醒等）做出不同反应，亲密度系统让互动更有温度
2. DSH Agent 可视化：绑定 DeepSeek Harness 后，Agent 的运行状态、任务进度、审批请求会实时映射为小鲸的表情和动作，让 AI 不再是黑盒
3. 轻量工作台：内置控制面板（小屋/设置/DSH/对话四页签）、自定义右键菜单、定时提醒、文件拖拽交互，是桌面端的轻量效率工具
4. 可扩展平台：声明式配置驱动（pet-spec.json），角色动作、互动、主题色均可通过配置调整，预留多角色切换和多 Agent 适配能力
5. Codex 模型路由（中转机）：内置 codex-router 中转机，把 Codex 的模型调用经 LiteLLM 网关路由到第三方 OpenAI 兼容 API（默认 DF API）。支持 API 密钥管理、模型列表、免登录/混合两种模式、用量与日志；免登录模式下第三方模型以原生 GPT 型号名顶替出现在 Codex 选择器

✨ 核心特性

🎨 像素风角色动画
- 36 个动画状态：基础动作（idle/walk/run/jump/sit/sleep）、情绪表情（happy/sad/angry/shy/scared/excited...）、行为彩蛋（dishwash/hug-doll/fly/dance/read...）
- 帧序列动画：walk 6 帧循环、run 4 帧循环、jump 3 帧一次性、idle CSS 呼吸动画 + 随机眨眼
- 86 张像素素材：512×512 透明 PNG，绿幕抠图 + 归一化处理
- 左右镜像复用：朝左动作通过 CSS transform 镜像，素材减半

🤖 DSH Agent 绑定
- HTTP + SSE 长连接：实时接收 DSH Agent 状态推送
- 状态→动画映射：Agent 运行中→walk、思考中→idle、出错→sad、需要审批→notify
- 审批联动：Agent 请求权限时，桌宠弹出带按钮的对话气泡，用户可直接允许/拒绝
- 任务提交与列表：通过桌宠向 DSH 提交任务、查看任务列表

🔌 Codex 模型路由（中转机）
- 内置中转机：codex-router 便携包随应用分发（安装包与绿色版均含），启动时自动部署并初始化状态目录（密钥/模型目录/网关配置），无需用户单独安装
- 两种模式：免登录（第三方模型顶替原生 GPT 型号名，无需 OpenAI 官方账号）+ 混合（官方账号登录，官方与第三方模型并存）
- 模型管理：API 密钥、模型列表、免登录槽位（最多 6 个）、子代理、用量与日志，全在「中转机控制台」弹窗内管理，无需打开网页
- 协议透明：把 Codex 的 responses 请求经 LiteLLM 网关转换为 chat completions 转发到第三方 OpenAI 兼容 API

💬 互动系统
- 6 种互动：点击头部、喂食、摸头、击掌、一起走路、摇篮曲
- 亲密度系统：互动增加亲密度，离线衰减，高亲密度解锁特殊动作和台词
- 对话气泡：自适应大小，支持审批型按钮、普通对话、状态提示
- 文件拖拽：拖拽文件到桌宠触发对应反应（成功/失败不同表情）

🖼️ 透明窗口与 UI
- 透明置顶窗口：人物抠图后真实透明，不遮挡桌面内容
- 可拖拽移动：按住人物拖动，边缘自动吸附
- 自定义右键菜单：懒创建的独立菜单窗口，非系统原生菜单
- 控制面板：页签化设计（小屋/设置/DSH/对话），亲密度、设置、DSH 状态、对话历史一目了然

⚙️ 声明式配置驱动
- pet-spec.json 统一管理角色、状态、触发器、互动、构建配置
- 修改配置无需改代码，热重载即可生效
- 内置 8 项 preflight 校验，确保配置和素材质量

🛠️ 技术栈

| 层级 | 技术 | 版本 |
|---|---|---|
| 运行时 | Electron | 37.x |
| 语言 | TypeScript | 5.x |
| 构建 | Webpack | 5.x |
| 打包 | electron-forge + Squirrel | - |
| 测试 | Vitest + Playwright | - |
| 素材处理 | sharp + 自定义抠图脚本 | - |
| DSH 通信 | Node 内置 http（无外部依赖） | - |
| 窗口管理 | 自定义透明窗口 + IPC | - |

🚀 快速开始

环境要求
- Node.js >= 20
- Windows 10/11 (x64)
- （可选）DSH（DeepSeek Harness）已启动并配置 Bridge

安装与运行

克隆项目
git clone
cd whalemaid-desktop-pet/app

安装依赖
npm install

开发模式启动（自动运行 8 项 preflight 校验）
npm run dev

代码检查
npm run check

运行测试
npm test

打包分发

Windows 安装包 (Squirrel)
npm run make:win

Windows 绿色免安装 (portable)
npm run portable:win

macOS 版本
npm run make:mac
npm run portable:mac

DSH 绑定配置

1. 确保 DSH（DeepSeek Harness）已安装并启动
2. 在 DSH 中启用 deskpet-bridge preset
3. 启动桌宠后，在控制面板 → DSH 页签中配置连接地址（默认 http://localhost:xxxx）
4. 连接成功后，小鲸会实时反映 Agent 状态

🐋 角色介绍：小鲸

| 属性 | 值 |
|---|---|
| 名称 | 小鲸 (WhaleMaid) |
| 种族 | 鲸鱼兽人（鱼鳍耳朵 + 鲸鱼尾巴） |
| 职业 | 女仆 |
| 性格 | 活泼、调皮、小恶魔、爱撒娇、忠诚 |
| 外貌 | 蓝色长卷发（渐变发尾）、鱼鳍耳朵、深蓝色鲸鱼尾、深蓝女仆裙、白色围裙（鲸鱼图案）、白色女仆发带 + 蓝色蝴蝶结、头顶呆毛 |

保留特征（AI 生成素材时必须保持）
1. 蓝色长卷发（薄荷绿渐变发尾）
2. 深蓝色鲸鱼尾巴
3. 鱼鳍耳朵（替代人类耳朵）
4. 深蓝色女仆连衣裙
5. 白色围裙（带鲸鱼图案）
6. 白色女仆发带 + 右侧蓝色蝴蝶结
7. 头顶呆毛（情绪指示器）

📋 功能清单

核心桌宠
- [x] 透明置顶窗口
- [x] 可拖拽移动 + 边缘吸附
- [x] 逐帧动画播放
- [x] 状态机管理
- [x] 对话气泡（自适应大小）

表情与动作
- [x] 11 基础状态（idle/blink/talk/walk/run/jump/sit/sleep/stretch/lie-down/prone）
- [x] 10 情绪状态（happy/sad/angry/shy/confused/surprised/sleepy/excited/scared/aggrieved）
- [x] 14 行为/移动/姿态状态（feed-fish/drink/coffee/work/fishing/dishwash/hug-doll/trip/fly/read/dance/heart/notify/edge-snap）
- [x] 帧序列动画（walk/run/jump）
- [x] CSS 呼吸动画（idle）

互动系统
- [x] 点击头部（pet-head）
- [x] 喂食（feed-fish）
- [x] 点击身体（tap）
- [x] 击掌（high-five）
- [x] 一起走路（walk-together）
- [x] 摇篮曲（lullaby）
- [x] 挑逗（tease）
- [x] 亲密度系统（增长 + 离线衰减）
- [x] 文件拖拽交互

DSH 绑定
- [x] HTTP + SSE 长连接
- [x] 状态→动画映射
- [x] 审批联动（带按钮气泡）
- [x] 任务提交（submit-task）
- [x] 任务列表（list-tasks）
- [ ] 多 Agent 适配（预留）

UI 与窗口
- [x] 自定义右键菜单（懒创建独立窗口）
- [x] 控制面板（页签化：小屋/设置/DSH/对话）
- [x] 定时提醒窗口
- [x] 托盘菜单
- [x] 三退出动作（退出桌宠 / 退出 DSH / 强制结束）

构建与分发
- [x] Windows 安装包 (Squirrel)
- [x] Windows 绿色免安装 (portable)
- [x] macOS 版本
- [x] 8 项 preflight 校验
- [x] 素材 QA 自动化

📁 项目结构

whalemaid-desktop-pet/
├── app/                              # 桌宠主应用
│   ├── src/
│   │   ├── main/                     # 主进程
│   │   │   ├── main.ts               # 入口：窗口管理 + IPC 路由
│   │   │   ├── dsh/                  # DSH 客户端模块
│   │   │   │   ├── client.ts         # HTTP + SSE 客户端
│   │   │   │   ├── adapter.ts        # 状态→动画映射 + 审批联动
│   │   │   │   └── types.ts          # 类型定义
│   │   │   └── data-validation.ts    # 数据校验
│   │   ├── preload.ts                # 预加载脚本
│   │   ├── shared/
│   │   │   └── contracts.ts          # IPC 契约定义
│   │   └── renderer/
│   │       ├── pet/                  # 桌宠窗口
│   │       │   ├── index.ts          # 状态机 + 逐帧动画 + 拖拽
│   │       │   └── state-machine.ts  # 状态机实现
│   │       ├── dashboard/            # 控制面板
│   │       ├── reminder/             # 提醒窗口
│   │       └── menu/                 # 右键菜单窗口
│   ├── assets/
│   │   └── pet/                      # 86 张像素素材 (512×512 PNG)
│   ├── tools/                        # 构建与工具脚本
│   │   ├── run-dev.mjs               # 开发启动器
│   │   ├── preflight.mjs             # 8 项 preflight 校验
│   │   ├── validate-spec.mjs         # pet-spec.json 校验
│   │   ├── qa-assets.mjs             # 素材质量检查
│   │   ├── recutout-hard.cjs         # 绿幕抠图脚本
│   │   ├── normalize-assets.cjs      # 素材归一化脚本
│   │   └── fix-spec-frames.cjs       # 帧复制脚本
│   ├── pet-spec.json                 # 声明式配置（角色/状态/互动/构建）
│   ├── .doubao-pet-builder.json      # 受保护文件哈希
│   ├── package.json
│   └── forge.config.js
├── docs/                             # 项目文档
│   ├── 桌面宠物项目书.md              # 项目全景 + 功能清单
│   ├── 行为文档.md                    # 开发记录 + 技术决策
│   ├── 对话文档.md                    # DSH 对接 + 联调记录
│   ├── 功能介绍.md                    # 用户向功能说明
│   └── 版权.md                        # 版权与合规
├── github-cover.png                  # GitHub 仓库封面
└── README.md                         # 本文件

🎮 状态与触发器

状态机概览

小鲸的行为由声明式状态机驱动，每个状态包含：
- frames：动画帧列表
- frameDurationMs：每帧时长
- triggers：触发该状态的事件列表
- anchor：人物锚点（用于对齐和拖拽）
- loop：是否循环播放

核心触发器类型

| 类型 | 示例 | 说明 |
|---|---|---|
| app: | app:start, app:close-with-sad | 应用生命周期 |
| ambient: | ambient:idle, ambient:sleep, ambient:coffee | 环境/时间触发 |
| pointer: | pointer:tap, pointer:drag-fast | 鼠标交互 |
| window: | window:edge-snap, window:drag | 窗口事件 |
| movement: | movement:left, movement:right | 自主移动 |
| interaction: | interaction:mood-happy, interaction:sit | 手动触发互动 |
| mood: | mood:happy, mood:angry | 情绪状态 |
| easter: | easter:dishwash, easter:fly | 彩蛋行为 |
| dsh: | dsh:notify | DSH Agent 事件 |
| reminder: | reminder:due | 定时提醒 |
| file:* | file:drop, file:drop-success | 文件拖拽 |

🔧 开发指南

添加新动作状态

1. 在 pet-spec.json 的 states 数组中添加新状态配置
2. 将素材 PNG 放入 src/assets/pet/
3. 运行 npm run check 验证配置和素材
4. 运行 npm run dev 查看效果

添加新触发器

1. 在 pet-spec.json 对应状态的 triggers 中添加
2. 在 tools/validate-spec.mjs 的 knownTriggers 集合中注册
3. 在主进程/渲染进程中触发对应事件

素材规范

- 格式：512×512 RGBA PNG（透明背景）
- 人物占比：约 72%（targetOccupancy: 0.72）
- 锚点：x≈0.54, y≈0.82（人物水平中心 + 底部）
- 命名：{stateId}-{frameIndex}.png
- 抠图：绿幕背景 (#00FF00) → tools/recutout-hard.cjs

常用命令

npm run dev          # 开发启动（含 preflight 校验）
npm run check        # 类型检查 + 全部校验
npm test             # 单元测试
npm run qa:assets    # 仅素材质量检查
npm run inspect:assets  # 素材可视化检查
npm run doctor       # 环境诊断
npm run make:win     # 打包 Windows 安装包

📄 文档体系

| 文档 | 用途 | 读者 |
|---|---|---|
| 桌面宠物项目书.md | 项目全景 + 功能清单 + 优先级 + 开发记录 | 所有人 |
| 行为文档.md | 开发记录 + 踩坑 + 技术决策 + 接口设计 | 开发者 |
| 对话文档.md | AI 助手必读 + DSH 对接状态 + 联调记录 | AI 编码助手 |
| 功能介绍.md | 用户向功能说明 | 终端用户 |
| 版权.md | 版权与合规说明 | 分发前自查 |

🤝 贡献

欢迎提交 Issue 和 Pull Request！

贡献指南
1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

代码规范
- TypeScript 严格模式
- 遵循项目内 AGENTS.md 指引
- 提交前运行 npm run check 确保全部校验通过

📜 许可证

本项目采用 MIT License 开源。

角色形象（小鲸）采用 CC BY-NC 4.0 协议：允许非商业使用、分享、改编，需署名，禁止商业用途。

详见 版权.md。

用像素风的温柔，陪伴每一个桌面时刻 🐋✨

Made with ❤️ by 豆包 + DeepSeek + ZCode