memPet-桌面宠物智能体

memPet 项目文档文档版本: 1.0最后更新: 2026-02-28项目类型: 智能桌面宠物应用目录1. 项目概述2. 核心功能3. 技术架构4. 环境搭建5. 快速开始6. 开发指南7. 常见问题8. 附录1. 项目概述1.1 项目简介memPet 是一款新一代智能桌面陪伴助手，具备持续记忆和主动推理能力的桌面宠物智能体。项目定位: 新一代智能桌面陪伴助手，具备长期记忆和主动学习和成长能力1.2 核心亮点• 持续记忆: 基于向量数据库（pgvector），记住所有对话和行为模式• 主动推理: 实时监控工作状态，智能生成个性化建议• 多性格系统: 4 种预设性格（友好型、活力型、专业型、傲娇型），同一场景不同表达方式1.3 典型应用场景• 疲劳提醒• 习惯学习• 专注保护• 个性化陪伴1.4 项目结构memPet-server/├── app/│   ├── main.py              # FastAPI 应用入口│   ├── models/              # 数据模型│   ├── services/            # 业务逻辑│   ├── api/                 # API 路由│   └── utils/               # 工具函数├── tests/                   # 测试文件├── .env.example             # 环境变量模板├── docker-compose.yml       # Docker 配置└── pyproject.toml           # Python 项目配置memPet-desktop/├── src/│   ├── pages/               # 页面组件│   ├── components/          # 通用组件│   ├── composables/         # 组合式函数│   ├── stores/              # Pinia 状态管理│   ├── services/            # API 服务│   ├── utils/               # 工具函数│   └── main.ts              # 应用入口├── src-tauri/│   ├── src/                 # Rust 源码│   ├── Cargo.toml           # Rust 项目配置│   └── tauri.conf.json      # Tauri 配置├── public/                  # 静态资源└── package.json             # Node.js 项目配置2. 核心功能2.1 持续记忆能力功能描述:• 基于向量数据库（pgvector）的记忆存储与检索• 记住所有对话内容和用户行为模式• 支持长期记忆的智能关联和上下文理解技术实现:• 使用 PostgreSQL + pgvector 扩展存储向量化记忆• 通过语义相似度检索相关历史记忆• 支持记忆的时间衰减和重要性评分2.2 主动推理引擎功能描述:• 实时监控用户工作状态（应用使用、工作时长、专注度等）• 智能分析上下文，在合适时机生成个性化建议• 冷却机制避免过度打扰，保护用户专注力推理流程:1. 收集用户行为数据（键盘、鼠标、应用使用等）2. 分析当前状态和历史模式3. 检索相关记忆作为上下文4. 生成个性化建议或关怀消息5. 根据冷却机制决定是否展示2.3 多性格系统预设性格:• 友好型: 温暖、关怀、鼓励• 活力型: 热情、积极、充满能量• 专业型: 理性、高效、专注• 傲娇型: 口是心非、关心但不直说性格表现:同一场景下，不同性格会有不同的表达方式和语气。2.4 应用场景示例场景 1: 智能疲劳干预触发条件: 连续编码 2.5 小时 + 键盘敲击频率下降 30%推理过程: 检索到上次提醒后用户继续工作了 40 分钟，判断为高专注状态但需要休息宠物行为: "检测到你已经连续写代码 2 个半小时了，而且敲键盘的速度明显变慢了呢。要不要起来活动一下？上次你休息 10 分钟后效率提升了不少哦~"场景 2: 上下文关怀触发条件: 检测到 IDE 报错频率增加 + 同一文件反复修改推理过程: 结合记忆发现用户在处理类似问题时曾搜索过相关文档，主动提供帮助宠物行为: "看起来这个 bug 有点棘手啊...我记得上周你遇到类似问题时查过官方文档的第 3 章，要不要我帮你找出来？"场景 3: 习惯预测触发条件: 每天 14:30 左右打开音乐播放器（连续 5 天）推理过程: 学习到用户下午有听音乐的习惯，在 14:25 主动询问宠物行为: "又到下午茶时间啦！要不要我帮你打开音乐播放器？你最近好像很喜欢在这个时候听歌放松一下~"场景 4: 专注保护触发条件: 检测到 Zoom/Teams 启动 + 日历显示会议中推理过程: 进入静默模式，暂停所有主动推理，会议结束后恢复并询问会议情况宠物行为: [静默模式] 会议结束后："会议开了 1 小时呢，辛苦啦！需要我帮你整理一下会议要点吗？"场景 5: 情绪感知触发条件: 检测到用户删除大量代码 + 长时间无操作 + 深夜时段推理过程: 结合历史记忆判断可能遇到挫折，提供情绪支持宠物行为: "看起来今天的进度不太顺利...我记得你上次遇到困难时，出去散步 15 分钟后就想到解决方案了。要不要试试？明天的你一定会感谢现在休息的自己~"场景 6: 个性化提醒触发条件: 用户连续 3 天在 23:00 后仍在工作推理过程: 检索到用户曾说过要早睡，结合性格（傲娇型）生成提醒宠物行为: "哼，又熬夜了...虽然我不是很在意啦，但是你之前不是说要早点睡的吗？身体可是革命的本钱，我可不想看到你明天顶着黑眼圈工作！"3. 技术架构3.1 整体架构┌─────────────────────────────────────────┐│         memPet-desktop (前端)           ││    Tauri + Vue 3 + TypeScript           ││  - Live2D 模型渲染                       ││  - 键鼠监控                              ││  - 用户交互界面                          │└──────────────┬──────────────────────────┘               │ HTTP/WebSocket               │┌──────────────▼──────────────────────────┐│         memPet-server (后端)            ││       FastAPI + PostgreSQL              ││  - 记忆存储与检索                        ││  - 主动推理引擎                          ││  - AI 对话服务                           │└──────────────┬──────────────────────────┘               │┌──────────────▼──────────────────────────┐│      PostgreSQL + pgvector              ││  - 用户对话记忆                          ││  - 系统观察记录                          ││  - 向量化存储                            │└─────────────────────────────────────────┘3.2 前端技术栈 (memPet-desktop)3.3 后端技术栈 (memPet-server)3.4 核心模块说明3.4.1 memPet-server 核心模块• 记忆存储 (Memory Storage): 存储用户对话和系统观察• 记忆检索 (Memory Retrieval): 基于向量相似度的智能检索• 主动推理 (Proactive Reasoning): 根据用户状态主动生成关心消息• 记忆增强对话 (Memory-Enhanced Chat): 结合历史记忆的智能对话3.4.2 memPet-desktop 核心模块• 跨平台支持: Windows、macOS、Linux 三平台支持• 键鼠监控: 根据键盘、鼠标操作同步动作• 自定义模型: 支持导入自定义 Live2D 模型• 隐私保护: 完全离线运行，不收集用户数据4. 环境搭建4.1 系统要求操作系统:• Windows 10/11• macOS 10.15+• Linux (Ubuntu 20.04+)硬件要求:• CPU: 双核及以上• 内存: 4GB RAM 最低，8GB 推荐• 硬盘: 2GB 可用空间4.2 开发工具安装4.2.1 后端开发环境Python 安装 (3.13+):• Windows: 从 python.org 下载安装• macOS: brew install python@3.13• Linux: sudo apt install python3.13uv 包管理工具安装:Windows (PowerShell):powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"macOS/Linux:curl -LsSf https://astral.sh/uv/install.sh | shPostgreSQL 安装 (14+):• 推荐使用 Docker: docker pull postgres:14• 或从 postgresql.org 下载安装Docker 安装:• Windows/macOS: 下载 Docker Desktop• Linux: sudo apt install docker.io docker-compose4.2.2 前端开发环境Node.js 安装 (18.0+):• 从 nodejs.org 下载 LTS 版本• 或使用 nvm: nvm install 18pnpm 安装 (8.0+):npm install -g pnpmRust 安装 (1.70+):curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shWindows 用户需额外安装:• Visual Studio C++ Build Tools• WebView2 Runtime4.3 Windows 系统特殊配置4.3.1 PowerShell 执行策略以管理员身份运行 PowerShell，执行：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser5. 快速开始5.1 克隆项目git clone https://github.com/your-username/memPet.gitcd memPet5.2 启动后端服务步骤 1: 进入后端目录cd memPet-server步骤 2: 启动 PostgreSQLdocker compose up -d postgres步骤 3: 配置环境变量# 复制环境变量模板cp .env.example .env# 编辑 .env 文件，填入必要配置# - DATABASE_URL: PostgreSQL 连接字符串# - OPENAI_API_KEY: OpenAI API 密钥# - 或 DASHSCOPE_API_KEY: 通义千问 API 密钥步骤 4: 启动服务方式 1 - 使用启动脚本（推荐）:./start.ps1          # Windows./start.sh           # macOS/Linux方式 2 - 手动启动:uv run fastapi dev app/main.py服务启动后访问: http://127.0.0.1:8000API 文档: http://127.0.0.1:8000/docs5.3 启动桌面应用步骤 1: 进入桌面应用目录cd memPet-desktop步骤 2: 安装依赖pnpm install步骤 3: 准备 Sidecar 启动器pnpm run sidecar:prepare这一步会生成 memPet-server-{platform}.exe 启动器文件。步骤 4: 启动开发模式pnpm run tauri:dev首次启动会编译 Rust 代码，需要等待几分钟。6. 开发指南6.1 项目目录结构6.1.1 memPet-server 目录结构memPet-server/├── app/│   ├── main.py              # FastAPI 应用入口│   ├── models/              # 数据模型│   ├── services/            # 业务逻辑│   ├── api/                 # API 路由│   └── utils/               # 工具函数├── tests/                   # 测试文件├── .env.example             # 环境变量模板├── docker-compose.yml       # Docker 配置└── pyproject.toml           # Python 项目配置6.1.2 memPet-desktop 目录结构memPet-desktop/├── src/│   ├── pages/               # 页面组件│   ├── components/          # 通用组件│   ├── composables/         # 组合式函数│   ├── stores/              # Pinia 状态管理│   ├── services/            # API 服务│   ├── utils/               # 工具函数│   └── main.ts              # 应用入口├── src-tauri/│   ├── src/                 # Rust 源码│   ├── Cargo.toml           # Rust 项目配置│   └── tauri.conf.json      # Tauri 配置├── public/                  # 静态资源└── package.json             # Node.js 项目配置6.2 常用开发命令6.2.1 memPet-server 命令# 启动开发服务器uv run fastapi dev app/main.py# 运行测试python tests/test_api.py# 启动 PostgreSQLdocker compose up -d postgres# 停止 PostgreSQLdocker compose down# 查看日志docker compose logs -f postgres6.2.2 memPet-desktop 命令# 安装依赖pnpm install# 准备 Sidecar 启动器pnpm run sidecar:prepare# 启动开发模式pnpm run tauri:dev# 代码检查pnpm run lint# 代码格式化pnpm run format# 构建应用pnpm run tauri:build# 构建图标pnpm run build:icon6.3 开发流程6.3.1 添加新功能1. 后端开发:– 在 app/models/ 定义数据模型– 在 app/services/ 实现业务逻辑– 在 app/api/ 添加 API 路由– 编写测试用例2. 前端开发:– 在 src/services/ 添加 API 调用– 在 src/stores/ 添加状态管理– 在 src/components/ 或 src/pages/ 实现 UI– 测试功能6.3.2 调试技巧后端调试:• 使用 FastAPI 自带的 /docs 接口测试 API• 使用 print() 或 logging 输出调试信息• 使用 PostgreSQL 客户端查看数据库前端调试:• 使用浏览器开发者工具• 使用 Vue DevTools 查看组件状态• 查看 Tauri 控制台输出6.4 代码规范6.4.1 Python 代码规范• 遵循 PEP 8 规范• 使用类型注解• 函数和类添加文档字符串• 变量命名使用 snake_case6.4.2 TypeScript 代码规范• 使用 ESLint 和 Prettier• 组件命名使用 PascalCase• 函数命名使用 camelCase• 常量命名使用 UPPER_SNAKE_CASE8. 附录8.1 API 接口文档后端服务提供以下主要 API 接口：8.1.1 记忆管理存储记忆POST /api/memory/storeContent-Type: application/json{  "content": "用户对话内容",  "type": "conversation",  "metadata": {}}检索记忆POST /api/memory/retrieveContent-Type: application/json{  "query": "查询内容",  "limit": 5}8.1.2 主动推理生成关心消息POST /api/proactive/generateContent-Type: application/json{  "context": {    "activity": "coding",    "duration": 150,    "intensity": 0.8  }}8.1.3 对话服务发送消息POST /api/chat/sendContent-Type: application/json{  "message": "用户消息",  "personality": "friendly"}完整 API 文档请访问: http://127.0.0.1:8000/docs8.2 配置文件说明8.2.1 .env 配置# 数据库配置DATABASE_URL=postgresql://user:password@localhost:5432/mempet# AI 服务配置（二选一）OPENAI_API_KEY=sk-xxxDASHSCOPE_API_KEY=sk-xxx# 服务配置HOST=127.0.0.1PORT=8000DEBUG=true# 记忆配置MEMORY_RETENTION_DAYS=90MEMORY_SIMILARITY_THRESHOLD=0.7# 推理配置PROACTIVE_COOLDOWN_MINUTES=30PROACTIVE_MIN_CONFIDENCE=0.68.2.2 tauri.conf.json 配置关键配置项：• identifier: 应用唯一标识符• windows: 窗口配置（大小、透明度等）• security: 安全配置（CSP、允许的 API 等）• bundle: 打包配置（图标、资源等）8.6 相关资源8.6.1 官方文档• Tauri 文档• Vue 3 文档• FastAPI 文档• PostgreSQL 文档8.6.2 社区资源• GitHub 仓库• 问题反馈• 讨论区8.7 贡献指南8.7.1 如何贡献1. Fork 项目仓库2. 创建功能分支: git checkout -b feature/your-feature3. 提交更改: git commit -m 'Add some feature'4. 推送到分支: git push origin feature/your-feature5. 提交 Pull Request8.7.2 代码审查标准• 代码符合项目规范• 包含必要的测试• 更新相关文档• 通过所有 CI 检查8.7.3 问题报告提交 Issue 时请包含：• 问题描述• 复现步骤• 预期行为• 实际行为• 系统环境信息• 相关日志或截图8.8 版本历史v1.0.0 (2026-02-28)新功能:• 基础桌面宠物功能• 持续记忆系统• 主动推理引擎• 多性格系统• Live2D 模型支持技术栈:• Tauri 2.0• Vue 3• FastAPI• PostgreSQL + pgvector8.9 许可证本项目采用 MIT License 开源协议。MIT LicenseCopyright (c) 2026 memPet ContributorsPermission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.8.10 致谢本项目灵感来源于 Bongo-Cat-Mver。感谢所有贡献者的支持和帮助！