浠艾福桌面宠物设计文档

日期： 2026-10-10 版本： v1.0 状态： 设计确认

一、项目概述

1.1 目标

构建一款 Windows 桌面宠物应用，通过浠艾福品牌吉祥物（浠宝/福宝）展现用户当前健康状态与任务执行情况，同时支持与用户互动完成打卡任务。

1.2 核心能力

能力	说明
状态展示	实时反映五维能量值、任务完成进度、健康打卡状态
互动提醒	支持喝水、吃药等定时提醒，用户可通过点击宠物确认完成
形象自定义	支持上传 PNG 形象 + JSON 配置，用户可完全自定义
小游戏	内置舒尔特方格等小游戏，宠物陪伴用户完成
顽皮行为	支持"偷图标"、"吃文档"等随机互动，增强陪伴感

二、系统架构

┌─────────────────────────────────────────────────────────────┐
│                     WPF 主进程 (C#)                         │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  API Client  │  │  状态管理器  │  │  托盘 / 快捷手势  │  │
│  │  (HttpClient)│  │  (StateMgr)  │  │  (NotifyIcon)    │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
│         │                 │                    │            │
│  ┌──────▼─────────────────▼────────────────────▼─────────┐  │
│  │                  WebView2 渲染层                       │  │
│  │  ┌──────────────────────────────────────────────────┐  │  │
│  │  │  HTML/JS 宠物引擎                                 │  │  │
│  │  │  - 精灵渲染 / CSS 动画 / 状态机                   │  │  │
│  │  │  - 拖拽 / 点击 / 悬停交互                         │  │  │
│  │  │  - 对话框气泡                                     │  │  │
│  │  └──────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │            JS ↔ C# Bridge (CoreWebView2)              │  │
│  │  C# → JS: window.cfcPetAPI.notifyState(data)         │  │
│  │  JS → C#: await chrome.webview.hostObjects.sync...    │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                  ┌──────────────────┐
                  │  CFC Backend     │
                  │  localhost:9082  │
                  │  JWT Bearer Token│
                  └──────────────────┘

模块职责

模块	职责
API Client	定时轮询 / 事件触发时拉取任务、能量、打卡数据；JWT 缓存与刷新
State Manager	将 API 数据转换为宠物状态（idle/happy/sad/busy/sleeping 等）
Bridge	C# 调用 JS 函数推送状态，JS 回调 C# 处理点击/拖拽事件
托盘 / 快捷手势	右键菜单（设置/最小化/退出）、键盘快捷键（显示/隐藏/唤醒）
WebView2 渲染层	接收状态数据，驱动精灵动画，处理用户交互

三、数据流（API → 宠物状态映射）

数据来源

CFC API	轮询频率	用途
`POST /api/tasks/today`	30s	当前用户今日任务列表
`POST /api/tasks/my-pending`	30s	待审核任务数
`POST /api/energy/overview`	60s	五维能量当前值
`POST /api/daily/checkin`	60s	今日打卡状态（身/智/心）
`POST /api/user/mascot/get`	首次 / 手动刷新	获取用户已选形象

状态映射表

数据字段	映射宠物状态	触发动作
今日任务全完成	`happy`	翅膀展开/甩尾巴 + 说话气泡"完成了！"
今日任务进行中（有1+未开始）	`busy`	低头看时间 / 来回踱步
今日任务超过2个未完成（截止后）	`worried`	皱眉 / 叹气
健康打卡完成	`excited`	转圈 / 蹦跳
健康打卡未做（下午未打卡）	`remind`	用爪子戳屏幕提示
身维度能量高	`energetic`	活跃动作，跳跃
身维度能量低	`tired`	趴下 / 打哈欠
智维度能量高	`curious`	歪头思考
所有维度都低（< 30%）	`sad`	垂头丧气 / 沉默
用户长时间无操作（>15min）	`sleeping`	闭眼蜷缩，呼吸起伏
用户正在操作键盘/鼠标	`watching`	抬头注视光标
等待用户互动（如喝水提醒）	`waiting_for_interaction`	戳屏幕 + 气泡提示
小游戏激活（如舒尔特）	`mini-game`	进入专注状态 + 数字/方块出现

状态流转时序

C# 侧 Timer (30s) ──► POST /api/tasks/today
          │
          ▼
StateMgr.Update(tasks, energy, checkin)
          │
          ▼
  计算宠物状态
          │
          ▼
window.cfcPetAPI.notifyState(state)
          │
          ▼
WebView2 JS 接收 → 触发对应动画帧 → 播放音效（可选）

四、形象配置格式（JSON Schema）

配置文件结构

{
  "version": "1.0",
  "type": "animal|human|custom",
  "species": "cockatiel|british_shorthair|human|other",
  "gender": "male|female|neutral",

  "image_base_url": "./assets/pets/xibao/",
  "default_image": "standing.png",

  "actions": {
    "idle": "wings_idle",
    "happy": "wings_spread",
    "busy": "head_tilt",
    "waiting_for_interaction": "hand_gesture",
    "success_animation": "celebrate",
    "sleeping": "breath_loop",
    "mini_game": "puzzle_active",

    // 【新增】用户自定义状态映射
    // 键为用户自定义状态名，值为对应的 CSS 动画类名或帧序列
    "custom_state_1": "user_animation_1",
    "custom_state_2": "user_animation_2"
  },

  "sounds": {
    "click": "pip.mp3",
    "complete": "cheer.mp3",
    "remind": "water_please.mp3"
  },

  "parameters": {
    "move_distance": 15,
    "animation_speed": 1.0,
    "interaction_timeout": 300
  }
}

用户自定义流程

用户放置 PNG 图片到 ~/.xaf-pet/images/<pet-name>/
同目录放置 pet-config.json（使用上述 Schema，可在 actions 中添加 custom_state_N 键值对）
应用启动时扫描所有配置文件夹
用户在"设置 → 自定义状态"界面管理自定义状态映射
C# 侧通过 window.cfcPetAPI.setCustomState("custom_state_1", data) 发送自定义状态

要求：

每只宠物需要一张基准 PNG（透明背景）+ 可选的动作帧图
CSS 动画驱动，无需多帧精灵图
支持最多 10 种用户自定义状态（通过配置文件 key 如 custom_state_1~custom_state_10 定义）

C# ↔ JS Bridge 新增接口

// C# → JS：设置自定义状态
public void SetCustomState(string stateName, object stateData);

五、交互规则与动作库

核心交互动作（内置库）

分类	动作名称	触发条件	说明
基础表情	`nod`	任务完成、确认打卡	缓慢上下点头
	`shake`	任务被拒绝、错误	横向摇头
	`blink`	默认/定时	3-5秒一次
	`look_around`	进入新环境	左右扫视
动物特有	`whistle`	用户登录、任务开始	鹦鹉吹口哨
	`ear_scrape`	用户有新提醒	耳朵抖动
	`tail_flick`	能量充足	尾巴摆动
	`paw_press`	完成打卡确认	前爪按压
	`belly_rub`	能量低 + 用户抚摸	腹部摩挲
人形动作	`wave`	问候/离开	手挥动
	`stretch`	早上唤醒	全身拉伸
	`clap`	任务成功	双手鼓掌
	`bow`	表达歉意/感谢	身体前倾
状态动作	`celebrate`	任务全完成	跳跃 + 爱心飞出
	`sad_animation`	任务连续失败	垂头、缓慢呼吸
	`worried_animation`	任务超过期限	皱眉、踱步
用户互动	`pet`	用户按住宠物 2s	触摸波纹 + 依偎动作
	`feed`	右键→喂食	吃掉食物动画
	`play_game`	点击宠物进入	小游戏模式
	`dismiss`	长按 3s	宠物飞走/消失
顽皮行为	`steal_icon`	随机（间隔 >10min）	宠物靠近某个图标，假装偷走
	`eat_document`	随机（用户保存文件后）	宠物做出"吃东西"动作
	`hide`	用户快速移动鼠标	宠物躲起来，几秒后重新出现

交互流程示例：喝水提醒

C# 侧检测：每 30s 轮询，发现今日未喝到水卡
状态变更：StateMgr 将状态设为 waiting_for_interaction，原因 drink_water
推送通知：window.cfcPetAPI.notifyState({state: "waiting_for_interaction", reason: "drink_water"})
JS 侧响应：宠物竖起爪子 + 气泡"该喝水啦~"
用户点击确认：window.cfcPetAPI.onInteract("confirm")
C# 处理：调用 POST /api/daily/checkin（水分项）
反馈循环：宠物播放 celebrate 动画，气泡"喝好啦！"

六、核心功能细节

6.1 拖拽与置顶

拖拽：左键按住拖动，支持多显示器
置顶：WPF TopMost=true，确保始终在其他窗口上方
自动隐藏：配置 auto_hide_when_idle=true 后，>15min 无操作自动隐藏到托盘
唤出：恢复任意点击、任务提醒触发

6.2 五维能量可视化

宠物颜色随五维能量值动态变化：

维度	颜色	能量高表现	能量低表现
身	`#FF8C42`	身体橙色发光	身体灰暗
智	`#6366F1`	眼睛亮紫色	眼睛黯淡
富	`#F59E0B`	金色光环环绕	光环消失
行	`#10B981`	翅膀/尾巴翠绿	颜色褪去
心	`#FF6B9D`	腮红/颈圈鲜艳	颜色淡出

6.3 声音策略

默认开启系统音效
每个状态可配置独立音频
用户可在设置中静音

6.4 游戏模式

支持的游戏类型： | 游戏 | 描述 | 入口 | |------|------|------| | 舒尔特方格 | 16格数字顺序点击 | 点击宠物 → "玩游戏" | | 记忆翻牌 | 翻牌配对 | 点击宠物 → "玩游戏" | | 数独 | 9×9 数独 | 点击宠物 → "玩游戏" |

游戏结束后，宠物播放 celebrate 或 sad_animation。

七、技术栈

层级	技术	说明
UI 框架	WPF (.NET 6)	原生 Windows 桌面框架
渲染引擎	WebView2	Edge 内核，支持现代 CSS/JS
API 调用	HttpClient + HttpClientFactory	异步轮询，JWT 缓存
动画	CSS Animation + JavaScript	跨状态动画驱动
配置存储	JSON 文件	用户配置 + 宠物形象
打包	MSIX / ClickOnce	单文件 exe 部署

八、文件结构

XafPet.Desktop/
├── src/
│   ├── App.xaml / App.xaml.cs           # 入口
│   ├── MainWindow.xaml / MainWindow.xaml.cs  # 主窗口
│   ├── PetEngine/
│   │   ├── WebViewHost.xaml             # WebView2 容器
│   │   ├── StateManager.cs              # 状态管理
│   │   ├── ApiClient.cs                 # CFC API 客户端
│   │   └── PetState.cs                  # 状态模型
│   ├── Assets/
│   │   ├── default-pet/                 # 默认浠宝/福宝
│   │   │   ├── standing.png
│   │   │   └── pet-config.json
│   │   └── sounds/                      # 音效
│   ├── Scripts/
│   │   ├── pet-engine.js                # 宠物渲染引擎
│   │   └── interactions.js              # 交互逻辑
│   └── Styles/
│       └── animations.css               # 动画定义
├── config/
│   └── app.json                         # 应用配置
└── user-data/                           # 用户数据（运行时生成）
    └── pets/
        └── <user-pet-name>/
            ├── standing.png
            └── pet-config.json

九、部署说明

目标平台：Windows 10/11
依赖：WebView2 Runtime（已预装在 Win10+，旧版需单独安装）
网络：需要能访问 http://localhost:9082（CFC 后端）
首次启动：引导用户输入 JWT Token 或扫码登录
自动更新：可选配置 GitHub Releases 自动检查更新

十、验收标准

宠物可正常显示在桌面，可拖拽移动
宠物置顶功能正常工作
五维能量变化时宠物颜色和状态正确反映
任务完成/未完成时宠物动画触发正确
喝水提醒可触发，用户点击后可完成打卡
小游戏（舒尔特方格）可正常运行
用户可上传自定义 PNG 形象并配置
应用可正常最小化到托盘
所有操作无内存泄漏，资源占用 < 50MB

十一、非功能性需求

需求	说明
性能	内存占用 < 50MB，CPU < 5%
响应	状态刷新延迟 < 2s
兼容性	Windows 10 (1803+)、Windows 11
安全性	JWT Token 加密存储，不记录密码
可用性	支持中文、英文语言包
可维护性	代码注释完整，支持后续扩展新游戏

下一步：编写实现计划（writing-plans）

2026-10-10-desktop-pet-design.md 15 KB Geçmiş Ham