---

📖 项目简介

像素桌宠是一只常驻桌面的像素风蓝发鲸鱼女仆 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 <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 状态

---

🐋 角色介绍：小鲸

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

保留特征（AI 生成素材时必须保持）

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

---

📋 功能清单

核心桌宠

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

表情与动作

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

互动系统

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

DSH 绑定

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

UI 与窗口

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

构建与分发

• Windows 安装包 (Squirrel)
• Windows 绿色免安装 (portable)
• macOS 版本
• 8 项 preflight 校验
• 素材 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。

---