whalemaid-desktop-pet

# 🐋 像素桌宠 (Pixel Desktop Pet) **像素风蓝发鲸鱼女仆桌面宠物 · DSH Agent 桌面入口** [](https://www.electronjs.org/) [](https://www.typescriptlang.org/) [](https://raw.githubusercontent.com/dfzjb/whalemaid-desktop-pet/main/#许可证) [](https://www.microsoft.com/windows) [](https://github.com/)

📖 项目简介

像素桌宠是一只常驻桌面的像素风蓝发鲸鱼女仆 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 校验，确保配置和素材质量

🛠️ 技术栈

🚀 快速开始

环境要求

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

安装与运行

# 克隆项目
git clone <repository-url>
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 状态

🐋 角色介绍：小鲸

保留特征（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：是否循环播放

核心触发器类型

🔧 开发指南

添加新动作状态

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 安装包

📄 文档体系

🤝 贡献

欢迎提交 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。