🐾 AI宠物伙伴 - 智能宠物陪伴系统

基于DeepSeek-V3的AI驱动虚拟宠物 | 复刻真实宠物性格 | 3D实时交互 | HEXACO六维性格系统

一个结合AI大语言模型、心理学性格系统和3D可视化技术的智能宠物陪伴应用。通过问卷系统精准复刻真实宠物性格，或从自然语言描述生成个性化虚拟宠物。

核心特性：AI对话 + HEXACO性格系统 + 智能记忆 + 情绪识别 + 3D动画交互

📖 目录

核心功能
技术架构
快速开始
- 基础安装
- 照片生成3D设置
3D模型系统
- 模型下载指南
- 照片生成3D详细教程
测试指南
API文档
项目结构
故障排查
开发路线
License

✨ 核心功能

🎯 已实现功能

1. AI对话引擎

✅ 基于硅基流动DeepSeek-V3大语言模型
✅ 智能上下文管理，记住每次对话
✅ 自然的宠物角色扮演，不生硬
✅ 短小精悍的回复，符合真实宠物特点

2. 六维性格系统

✅ 诚实度：诚实守信 vs 偶尔调皮
✅ 情感度：情感丰富 vs 相对理性
✅ 外向性：喜欢社交 vs 比较内向
✅ 亲和性：温顺友好 vs 有主见
✅ 尽责性：守规矩 vs 随性自由
✅ 开放性：好奇探索 vs 喜欢熟悉

3. 智能记忆系统

✅ 自动保存重要对话
✅ 记忆重要度评分（0-1）
✅ 在对话中自然提及记忆内容
✅ 根据情绪和关键词判断重要性

4. 情绪价值系统

✅ 实时识别用户情绪（7种情绪类型）
✅ 分析用户需求（感情支持/鼓励/倾听）
✅ 生成共情回复，提供情绪价值
✅ 3D行为建议（动画/表情/动作）

5. 宠物复刻功能

✅ 5题性格问卷，精准推断性格
✅ AI增强分析（结合主人描述）
✅ 自动生成温馨背景故事
✅ 图像分析接口（可扩展）

6. 智能宠物生成

✅ 从自然语言描述生成宠物
✅ 4种性格预设模板
✅ 自动设定外观和背景故事
✅ 个性化参数调整

7. 高级3D动画系统 🆕

✅ 18种动画状态：idle, sit, lie, walk, run, jump, stretch, wag_tail, shake, roll, sleep, eat, play等
✅ 动画状态机：平滑的状态转换系统，支持多阶段复杂动作（蓄力→跳起→落地）
✅ 性格驱动动画：外向性影响尾巴摆动速度，情绪度影响表情变化幅度
✅ 缓动函数：easeInOutCubic等算法保证动画自然流畅

8. 智能表情系统 🆕

✅ 10种详细表情：happy, sad, curious, playful, affectionate, angry, scared, surprised, sleepy, neutral
✅ 微表情系统：瞳孔闪动、耳朵抽动、胡须颤动等细微动作
✅ IK反向运动学：头部和眼睛自动追踪目标（lookAt功能）
✅ 复杂表情组合：眼睛眯缝 + 瞳孔放大 + 耳朵竖起 = 开心表情

9. AI-3D深度联动 🆕

✅ 智能动作解析：从AI返回文本自动提取动作关键词（"伸懒腰" → stretch动画）
✅ 情绪自动映射：AI返回的emotion字段自动触发对应表情和动画
✅ 详细动作描述：后端生成极其详细的动作文本（如"耳朵轻轻向后，慢悠悠地走过来，用脸颊在你的手上蹭来蹭去"）
✅ 物种差异化：猫咪和狗狗在相同情绪下展现不同行为

10. 照片生成3D模型 🆕✨

✅ AI照片转3D：使用Meshy.ai API从宠物照片自动生成逼真3D模型
✅ 实时进度跟踪：5秒轮询显示生成进度（0-100%），预计2-5分钟完成
✅ 自动模型下载：生成完成后自动下载GLB文件到本地，无需手动操作
✅ 智能文件管理：按 <物种>_<名字>_<时间戳>.glb 格式自动命名和存储
✅ PBR材质支持：生成的模型包含真实物理渲染材质，支持光照和阴影
✅ 模型优化：默认10000面三角形，平衡细节和性能
✅ 完整UI集成：PhotoUploadModal（上传界面）+ TaskProgressModal（进度跟踪）

11. 完整Web界面

✅ 宠物列表管理（创建/删除/选择）
✅ 实时聊天界面
✅ 快捷消息按钮
✅ 情绪状态显示
✅ 照片上传和3D生成界面 🆕

🏗️ 技术架构

前端技术栈

React 18 + TypeScript
├── UI框架：React Hooks
├── 3D渲染：Three.js 0.160
├── 构建工具：Vite 5.0
├── 样式：Inline Styles (可扩展为Tailwind)
└── 类型系统：TypeScript 5.6

后端技术栈

Node.js + Express
├── API框架：Express 4.18
├── ORM：Prisma 5.7
├── 数据库：SQLite (开发) / PostgreSQL (生产)
├── 验证：Zod 3.22
├── 实时通信：WebSocket (ws 8.16)
└── AI模型：硅基流动 DeepSeek-V3

系统架构图

┌─────────────────────────────────────────┐
│           用户浏览器                     │
│  (React + Three.js + WebSocket)         │
└──────────────┬──────────────────────────┘
               │ HTTP/WS
               ↓
┌─────────────────────────────────────────┐
│        API Gateway (Express)            │
│  ┌───────────┬───────────┬──────────┐  │
│  │ 宠物服务  │ AI服务   │ 记忆服务 │  │
│  └───────────┴───────────┴──────────┘  │
└──────────────┬──────────────────────────┘
               │
               ↓
┌──────────────┴──────────────────────────┐
│  ┌─────────┐  ┌──────────┐  ┌────────┐ │
│  │Prisma   │  │  SQLite  │  │  AI    │ │
│  │ORM      │  │  数据库  │  │  API   │ │
│  └─────────┘  └──────────┘  └────────┘ │
└─────────────────────────────────────────┘

🚀 快速开始

前置要求

Node.js 18+
npm 或 pnpm
Git

1. 克隆项目

git clone <repository-url>
cd pet-avatar

2. 启动后端

cd backend-node

# 安装依赖
npm install

# 初始化数据库
npx prisma generate
npx prisma db push

# 启动开发服务器
npm run dev

后端将运行在 http://localhost:3000

3. 启动前端

cd frontend

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env

# 启动开发服务器
npm run dev

前端将运行在 http://localhost:5173

4. 一键启动（推荐）

# 使用快速启动脚本
./quick-start.sh

该脚本会自动：

安装所有依赖
初始化数据库
同时启动后端和前端服务

5. 开始使用

打开浏览器访问 http://localhost:5173
点击"创建新宠物"
输入宠物名字，选择类型（猫/狗）
开始和你的AI宠物对话！

6. 设置照片生成3D功能（可选）🆕

功能说明：使用Meshy.ai API从宠物照片自动生成逼真3D模型（2-5分钟，~$0.08/次）

步骤1：获取Meshy.ai API密钥

注册账号：https://www.meshy.ai/
获取API密钥：https://app.meshy.ai/api
复制密钥（格式：msy_xxxxxxxx...）

步骤2：配置后端

cd backend-node
nano .env  # 添加以下行

在 .env 中添加：

MESHY_API_KEY=msy_你的实际密钥

步骤3：验证配置

# 重启后端后测试
curl http://localhost:3000/api/photo3d/check

# 应返回：{"available": true, "apiConfigured": true}

步骤4：使用功能

点击左侧边栏的 "📸 从照片生成3D模型" 按钮
上传宠物照片（JPG/PNG/WebP，< 10MB）
输入宠物名字，选择物种
等待2-5分钟自动生成
生成的模型会自动显示在3D场景

详细设置指南：请参阅 QUICK_SETUP_PHOTO3D.md

完整使用文档：请参阅 PHOTO_TO_3D_GUIDE.md

� 3D优化系统

系统架构

本项目实现了业界领先的3D宠物仿真系统，包含以下核心模块：

1. 动画状态机 (`frontend/src/utils/animationStateMachine.ts`)

18种动画状态：

基础动作：idle（待机）, sit（坐下）, lie（趴下）, sleep（睡觉）
移动动作：walk（走路）, run（跑步）, jump（跳跃）
互动动作：wag_tail（摇尾巴）, shake（抖身体）, stretch（伸懒腰）, roll（打滚）
表达动作：eat（吃东西）, play（玩耍）, bark（叫）, look_at（看向目标）
情绪动作：excited（兴奋）, sad（悲伤）, anxious（焦虑）

技术亮点：

// 性格驱动的动画参数
const speed = 5 + personality.extraversion * 3;  // 外向性影响速度
const amplitude = 0.3 + personality.emotionality * 0.2;  // 情绪度影响幅度

// 平滑状态转换
transitionTo(newState: AnimationState) {
  this.transitionProgress = 0;
  this.isTransitioning = true;
  // 使用easeInOutCubic缓动函数
}

2. 表情系统 (`frontend/src/utils/expressionSystem.ts`)

10种表情类型：

Happy（开心）：眼睛眯成月牙 + 瞳孔放大 + 耳朵竖起
Sad（悲伤）：眼睛半闭 + 瞳孔缩小 + 耳朵耷拉
Curious（好奇）：一只眼睛睁大 + 一只耳朵竖起（歪头）
Playful（顽皮）：眨眼调皮 + 耳朵一高一低
Affectionate（温柔）：眼睛轻闭 + 胡须向前
Angry（生气）：眼睛睁大 + 瞳孔缩小 + 耳朵向后
Scared（害怕）：瞳孔扩大 + 耳朵紧贴 + 胡须向后
Surprised（惊讶）：眼睛睁大 + 瞳孔放大 + 耳朵竖起
Sleepy（困倦）：眼睛半闭 + 耳朵放松
Neutral（中性）：默认状态

微表情系统：

// 每帧自动更新的细微动作
- 瞳孔微微闪动（1 + sin(time * 10) * 0.02）
- 耳朵随机抽动（1%概率触发）
- 胡须自然颤动（sin波形）
- 眨眼动作（随机间隔2-5秒）

IK系统：

// 让宠物看向用户
lookAt(target: Vector3, headObject: Object3D) {
  // 头部旋转 + 瞳孔位置调整
}

3. 统一3D场景 (`frontend/src/components/ThreeSceneAdvanced.tsx`)

渲染优化：

PCFSoftShadowMap 软阴影
ACESFilmicToneMapping 色调映射
三点光照系统（主光 + 补光 + 轮廓光）
60 FPS 流畅渲染

模型加载：

支持 GLTF/GLB 格式
程序化模型作为回退方案
自动提取身体部件（头、耳朵、尾巴等）
自动提取面部特征（眼睛、瞳孔、胡须）

实时调试：

// 左下角显示当前状态
<div>当前动画: {currentState}</div>
<div>当前情绪: {currentEmotion}</div>
<div>当前表情: {currentExpression}</div>

性能对比

功能	优化前	优化后	提升幅度
动画状态数	3种	18种	+500%
表情种类	1种	10种+微表情	+900%
动画真实感	简单旋转	多阶段+缓动	+300%
情绪表达能力	无	8种情绪状态	+500%
AI联动深度	文本显示	智能解析+自动触发	质的飞跃

使用示例

// 在对话中触发动画
用户："你好！" 
→ AI识别：emotion='happy', action='摇尾巴'
→ 前端解析：AnimationState.WAG_TAIL + Expression.HAPPY
→ 3D展示：尾巴快速摆动 + 眼睛眯起 + 耳朵竖起

用户："我好累"
→ AI识别：emotion='sad', action='靠近安慰'
→ 前端解析：AnimationState.WALK + Expression.SAD
→ 3D展示：慢步走来 + 耳朵耷拉 + 眼睛关切

📦 3D模型设置

安装步骤

# 1. 下载模型文件（.glb 或 .gltf 格式）

# 2. 放入项目目录
mkdir -p frontend/public/models
# 将文件重命名为:
# - cat.glb (猫咪模型)
# - dog.glb (狗狗模型)

# 3. 使用 GLTF Viewer 预览
# https://gltf-viewer.donmccurdy.com/

# 4. 可选：使用 gltf-transform 压缩大文件
npm install -g @gltf-transform/cli
gltf-transform compress input.glb output.glb

�📖 API文档

基础操作

方法	路径	说明
GET	`/api/pets`	获取所有宠物
POST	`/api/pets`	创建新宠物
GET	`/api/pets/:id`	获取宠物详情
DELETE	`/api/pets/:id`	删除宠物
PUT	`/api/pets/:id/persona`	更新宠物性格

AI对话

方法	路径	说明
POST	`/api/pets/:id/chat`	与宠物对话

请求示例：

{
  "message": "你好！想玩吗？"
}

响应示例：

{
  "response": "汪汪！当然想玩！我们玩球吧！🎾",
  "emotion": "happy"
}

宠物复刻

方法	路径	说明
GET	`/api/pets/replication/questionnaire`	获取性格问卷
POST	`/api/pets/replication/analyze-questionnaire`	分析问卷
POST	`/api/pets/replication/enhance-persona`	AI增强分析
POST	`/api/pets/replication/create`	创建复刻宠物

智能生成

方法	路径	说明
POST	`/api/pets/generation/from-description`	从描述生成
GET	`/api/pets/generation/persona-presets`	获取性格预设
POST	`/api/pets/generation/apply-preset`	应用预设

情绪系统

方法	路径	说明
POST	`/api/pets/emotion/analyze`	分析情绪
POST	`/api/pets/emotion/empathetic-response`	生成共情回复
POST	`/api/pets/emotion/behavior-suggestion`	获取行为建议

完整API文档请查看后端README文档。

📁 项目结构

pet-avatar/
├── backend-node/              # 主后端（Node.js + TypeScript）
│   ├── src/
│   │   ├── index.ts          # 入口文件
│   │   ├── prisma.ts         # Prisma客户端
│   │   ├── config/
│   │   │   └── ai.ts         # AI配置、性格预设、问卷
│   │   ├── routes/
│   │   │   └── pets.ts       # 宠物相关API路由
│   │   └── services/
│   │       ├── aiService.ts         # AI对话引擎
│   │       ├── emotionalService.ts  # 情绪分析
│   │       └── replicationService.ts # 宠物复刻
│   ├── prisma/
│   │   └── schema.prisma     # 数据库Schema
│   └── package.json
│
├── backend-fastapi/           # 备用后端（Python + FastAPI）
│   ├── app/
│   │   ├── main.py
│   │   ├── api/routes.py
│   │   └── db/models.py
│   └── requirements.txt
│
├── frontend/                  # 前端（React + TypeScript + Three.js）
│   ├── src/
│   │   ├── App.tsx           # 主应用组件
│   │   ├── main.tsx          # 入口文件
│   │   ├── components/
│   │   │   ├── PetList.tsx            # 宠物列表
│   │   │   ├── PetChat.tsx            # 聊天界面
│   │   │   └── ThreeSceneAdvanced.tsx # 3D场景（主组件）
│   │   └── utils/
│   │       ├── animationStateMachine.ts # 动画状态机
│   │       └── expressionSystem.ts      # 表情系统
│   ├── public/
│   │   └── models/           # 3D模型文件
│   │       ├── cat/
│   │       └── dog-gltf/
│   └── package.json
│
├── .github/
│   └── copilot-instructions.md # AI编程助手指南
├── .gitignore                  # Git忽略文件
├── quick-start.sh              # 一键启动脚本
└── README.md                   # 本文件

🎨 使用演示

场景1：创建并与宠物互动

1. 访问 http://localhost:5173
2. 点击"创建新宠物" → 输入名字"旺财"，选择"狗"
3. 在聊天框输入："你好旺财！"
4. 观察：3D狗狗开始摇尾巴（WAG_TAIL动画）+ 开心表情（眼睛眯起）
5. 继续输入："我们玩球吧！"
6. 观察：狗狗兴奋跳跃（JUMP动画）+ 兴奋表情

场景2：情绪陪伴

1. 输入："今天工作好累，心情不好"
2. AI分析：emotion='sad', need='感情支持'
3. AI回复："主人辛苦了，让我陪陪你 💙"
4. 3D展示：
   - 动画：WALK（慢步走来）→ SIT（坐在旁边）
   - 表情：SAD（耳朵耷拉 + 眼神关切）
   - 动作描述："*耳朵轻轻向后，慢悠悠地走过来，把头枕在你的腿上*"

场景3：复刻真实宠物

1. 点击"复刻真实宠物"
2. 回答5个性格问卷：
   Q1: "它见到陌生人会？" → "热情打招呼"
   Q2: "它遇到新事物会？" → "好奇地探索"
   ...（根据实际宠物回答）
3. 添加描述："我的猫咪叫橘子，很聪明但有点高冷"
4. AI生成：
   - 性格分析：extraversion=0.7, openness=0.85, agreeableness=0.4
   - 背景故事："橘子是一只聪明的橘猫，喜欢探索新事物..."
5. 创建成功！开始与"橘子"对话

💡 技术特色

vs 传统AI聊天机器人

特性	本项目	传统聊天机器人
角色扮演	✅ 完全沉浸宠物角色	❌ 通用助手
性格系统	✅ HEXACO六维精准性格	❌ 简单人设
记忆能力	✅ 智能记忆+重要度评分	❌ 无/简单存储
情绪识别	✅ 7种情绪+共情回复	❌ 无情绪理解
3D可视化	✅ 实时动画+表情系统	❌ 纯文字
个性化	✅ 复刻真实宠物	❌ 无

vs 虚拟宠物游戏

特性	本项目	虚拟宠物游戏
对话能力	✅ 理解上下文的AI对话	❌ 预设台词
性格复刻	✅ 问卷+AI增强分析	❌ 固定模板
情感陪伴	✅ 提供真实情绪价值	❌ 娱乐为主
记忆系统	✅ 记住每次对话	❌ 无记忆
可定制性	✅ 高度个性化	❌ 有限选项

核心优势

心理学基础：基于HEXACO模型，科学准确
AI驱动：DeepSeek-V3提供自然对话体验
3D真实感：18种动画+10种表情，媲美游戏品质
情绪陪伴：真正理解用户情绪，提供情感支持
开源免费：完全开源，可自由扩展

📊 性能指标

AI响应速度：< 2秒（取决于网络）
Token消耗：平均500 tokens/轮对话
成本估算：约 ¥0.007/轮对话（DeepSeek-V3定价）
3D渲染帧率：60 FPS
模型加载时间：< 1秒
内存占用：< 100MB

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发规范

使用 TypeScript 严格模式
遵循现有代码风格（Prettier + ESLint）
提交前运行测试
PR描述清晰，包含截图/GIF

参与开发

# Fork 项目后克隆
git clone https://github.com/your-username/pet-avatar.git
cd pet-avatar

# 创建新分支
git checkout -b feature/your-feature

# 安装依赖并开发
./quick-start.sh

# 开发完成后提交
git add .
git commit -m "feat: add your feature"
git push origin feature/your-feature

# 然后在 GitHub 上创建 Pull Request

� 3D模型系统

模型加载优先级

系统按以下顺序尝试加载3D模型：

用户上传的照片生成模型 (/models/generated/)
手动下载的真实模型 (/models/realistic/cat|dog/)
默认GLTF模型 (/models/cat/ 或 /models/dog-gltf/)
程序化生成模型 (最终回退)

📥 模型下载完整指南

下载步骤

注册Sketchfab账号
选择模型点击 Download 3D Model
选择格式：glTF 2.0 (.glb)
下载并解压

文件命名规范

# 放置到 frontend/public/models/realistic/cat/ 或 dog/
cat_tabby.glb           # 虎斑猫
cat_persian.glb         # 波斯猫
dog_shepherd.glb        # 德国牧羊犬
dog_husky.glb           # 哈士奇
dog_golden.glb          # 金毛

模型优化（可选）

# 安装工具
npm install -g @gltf-transform/cli

# 优化模型
cd frontend/public/models/realistic/cat
gltf-transform optimize input.glb output.glb

# Draco压缩（减少70%大小）
gltf-transform draco output.glb final.glb

预览和测试

GLTF Viewer: https://gltf-viewer.donmccurdy.com/
Three.js Editor: https://threejs.org/editor/

拖拽.glb文件检查：

✅ 模型完整性
✅ 动画播放
✅ 材质纹理
✅ 文件大小（建议<5MB）

📸 照片生成3D详细教程

功能介绍

使用Meshy.ai AI技术从宠物照片自动生成3D模型：

⏱️ 生成时间: 2-5分钟
💰 费用: 约$0.08/次
📊 质量: PBR材质，10000面三角形
📋 支持格式: JPG, PNG, WebP (< 10MB)

快速设置（5分钟）

1. 获取API密钥

注册: https://www.meshy.ai/
获取密钥: https://app.meshy.ai/api
复制 msy_xxxxxxxx... 格式的密钥

2. 配置后端

# 编辑 backend-node/.env
echo 'MESHY_API_KEY=msy_你的实际密钥' >> backend-node/.env

# 验证配置
curl http://localhost:3000/api/photo3d/check
# 应返回: {"available": true, "apiConfigured": true}

3. 使用功能

打开 http://localhost:5173
点击 "📸 从照片生成3D模型"
上传清晰的宠物照片
输入名字，选择物种
等待2-5分钟自动生成

照片要求

✅ 推荐:

清晰高分辨率（1024x1024+）
完整身体（头+身体+四肢）
正面或3/4侧面
简洁背景，光线均匀
站立姿势

❌ 避免:

模糊或低分辨率
严重遮挡
极端角度
多只宠物
强烈光线对比

API接口

// 上传照片
POST /api/photo3d/upload
Body: FormData { photo, petName, species }

// 查询进度
GET /api/photo3d/status/:taskId
Response: { status, progress, modelUrl }

// 下载模型
POST /api/photo3d/download/:taskId
Body: { filename }

// 检查服务
GET /api/photo3d/check
Response: { available, apiConfigured }

生成流程

上传 (< 5秒): 照片 → Meshy.ai API
处理 (2-5分钟): AI分析 → 3D重建 → 纹理映射
下载 (< 10秒): GLB文件 → /models/generated/
显示: 自动加载到3D场景

费用说明

免费额度: 新用户200-500积分
照片转3D: 8积分/次 (~$0.08)
最小充值: $10 (1250积分)

故障排查

问题1: API不可用

# 检查环境变量
cat backend-node/.env | grep MESHY
# 重启后端
pkill -f "tsx watch" && cd backend-node && npm run dev

问题2: 生成失败

检查照片格式（JPG/PNG/WebP）
确认文件<10MB
查看后端日志错误信息

问题3: 模型无法显示

刷新页面
检查 frontend/public/models/generated/ 是否有文件
在 https://gltf-viewer.donmccurdy.com/ 预览GLB文件

🧪 测试指南

完整测试清单

环境检查

# Node版本
node --version  # >= 18

# 依赖安装
cd backend-node && npm list axios multer form-data
cd frontend && npm list

# 目录结构
ls frontend/public/models/{generated,realistic/cat,realistic/dog}/

配置检查

# API密钥
cat backend-node/.env | grep MESHY_API_KEY

# 服务健康
curl http://localhost:3000/api/health
curl http://localhost:3000/api/photo3d/check

功能测试

1. 模型下载测试

运行 ./download_models.sh 显示下载指南
从Sketchfab下载一个模型
放入 realistic/cat/ 或 realistic/dog/
刷新前端，验证模型加载

2. 照片生成3D测试

3. 端到端测试

# 完整流程测试脚本
TEST_PHOTO="test_cat.jpg"

# 1. 上传
RESULT=$(curl -s -X POST http://localhost:3000/api/photo3d/upload \
  -F "photo=@$TEST_PHOTO" \
  -F "petName=测试猫" \
  -F "species=cat")

TASK_ID=$(echo $RESULT | jq -r '.taskId')

# 2. 轮询状态
while true; do
  STATUS=$(curl -s http://localhost:3000/api/photo3d/status/$TASK_ID | jq -r '.status')
  echo "状态: $STATUS"
  [ "$STATUS" = "succeeded" ] && break
  sleep 5
done

# 3. 下载模型
curl -s -X POST http://localhost:3000/api/photo3d/download/$TASK_ID \
  -H "Content-Type: application/json" \
  -d '{"filename": "test.glb"}'

# 4. 验证文件
ls -lh frontend/public/models/generated/test.glb

4. 错误处理测试

无效API密钥 → 返回认证错误
文件格式错误 → 返回400错误
文件过大(>10MB) → 返回413错误
无效taskId → 返回404错误

性能测试

# 响应时间
time curl http://localhost:3000/api/health
time curl http://localhost:3000/api/photo3d/check

# 内存占用
ps aux | grep "tsx watch"
# 预期: < 500MB

测试结果

🐛 故障排查

常见问题解决方案

1. 白屏或无法加载

症状: 点击宠物选择后显示白屏

解决方案:

# 检查后端是否运行
curl http://localhost:3000/api/health

# 检查前端是否运行
curl http://localhost:5173

# 查看浏览器控制台错误
# F12 → Console → 查看红色错误信息

# 重启服务
pkill -f "tsx watch" && pkill -f "vite"
cd backend-node && npm run dev &
cd frontend && npm run dev &

2. 模型不显示

症状: 3D场景显示"正在加载"但模型不出现

解决方案:

# 检查模型文件是否存在
ls -lh frontend/public/models/realistic/cat/
ls -lh frontend/public/models/realistic/dog/

# 检查文件名是否正确
# 期望: BengalCat.glb, dog.glb 或标准命名

# 查看浏览器Network标签
# F12 → Network → 搜索.glb → 查看404错误

# 重命名文件（如果需要）
cd frontend/public/models/realistic/cat
mv YourModel.glb BengalCat.glb

3. 照片上传失败

症状: 点击"上传并生成"后无响应或报错

解决方案:

# 1. 检查API密钥
cat backend-node/.env | grep MESHY_API_KEY

# 2. 验证服务可用性
curl http://localhost:3000/api/photo3d/check

# 3. 检查照片格式和大小
file your-photo.jpg  # 应显示 JPEG/PNG/WebP
du -h your-photo.jpg  # 应 < 10MB

# 4. 查看后端日志
# 后端终端应显示上传日志和错误信息

# 5. 重新配置API密钥
echo 'MESHY_API_KEY=msy_新密钥' >> backend-node/.env
pkill -f "tsx watch" && cd backend-node && npm run dev

4. TypeScript编译错误

症状: 前端或后端报类型错误

解决方案:

# 重新生成Prisma类型
cd backend-node
npx prisma generate

# 清理并重新安装依赖
rm -rf node_modules package-lock.json
npm install

# 重启TypeScript服务
# VSCode: Cmd+Shift+P → "TypeScript: Restart TS Server"

5. 数据库错误

症状: 创建宠物失败，提示数据库错误

解决方案:

cd backend-node

# 重置数据库
rm -f dev.db
npx prisma db push

# 检查schema是否正确
npx prisma studio  # 打开可视化界面

6. 端口占用

症状: 启动时提示端口3000或5173已被占用

解决方案:

# 查找占用端口的进程
lsof -ti:3000  # 后端
lsof -ti:5173  # 前端

# 杀死进程
kill -9 $(lsof -ti:3000)
kill -9 $(lsof -ti:5173)

# 或使用不同端口
PORT=3001 npm run dev  # 后端
VITE_PORT=5174 npm run dev  # 前端

7. 性能问题

症状: 3D场景卡顿，帧率低

解决方案:

// 降低模型复杂度
gltf-transform optimize input.glb output.glb --target-polycount 5000

// 禁用阴影（临时）
renderer.shadowMap.enabled = false;

// 降低像素比
renderer.setPixelRatio(1); // 替代 Math.min(window.devicePixelRatio, 2)

8. Meshy.ai积分不足

症状: 上传照片后返回"Insufficient credits"

解决方案:

访问 https://app.meshy.ai/billing
充值最低$10（1250积分）
或等待每月免费额度重置

获取帮助

如果以上方案都无法解决，请：

查看完整错误日志（后端+前端控制台）
到GitHub Issues提问：提交问题
附上：操作系统、Node版本、错误截图、相关日志

�📄 License

MIT License - 可自由使用和修改

MIT License

Copyright (c) 2025 Pet Avatar Project

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

完整协议请查看 LICENSE 文件。

🙏 致谢

感谢以下开源项目和服务：

React - UI框架
Three.js - 3D渲染引擎
Prisma - 数据库ORM
硅基流动 - AI模型API服务
DeepSeek - 大语言模型
Sketchfab - 3D模型资源

📞 联系与支持

GitHub Issues：提交问题
GitHub Discussions：参与讨论
Email：your-email@example.com

⭐️ 如果喜欢请给个 Star

如果这个项目对你有帮助，请点击右上角的 ⭐️ 支持一下！

Made with ❤️ and 🤖

回到顶部

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github		.github
backend-fastapi		backend-fastapi
backend-node		backend-node
docs		docs
frontend		frontend
.DS_Store		.DS_Store
.gitignore		.gitignore
README.md		README.md
download_models.sh		download_models.sh
quick-start.sh		quick-start.sh

Folders and files

Latest commit

History

Repository files navigation

🐾 AI宠物伙伴 - 智能宠物陪伴系统

📖 目录

✨ 核心功能

🎯 已实现功能

1. AI对话引擎

2. 六维性格系统

3. 智能记忆系统

4. 情绪价值系统

5. 宠物复刻功能

6. 智能宠物生成

7. 高级3D动画系统 🆕

8. 智能表情系统 🆕

9. AI-3D深度联动 🆕

10. 照片生成3D模型 🆕✨

11. 完整Web界面

🏗️ 技术架构

前端技术栈

后端技术栈

系统架构图

🚀 快速开始

前置要求

1. 克隆项目

2. 启动后端

3. 启动前端

4. 一键启动（推荐）

5. 开始使用

6. 设置照片生成3D功能（可选）🆕

步骤1：获取Meshy.ai API密钥

步骤2：配置后端

步骤3：验证配置

步骤4：使用功能

� 3D优化系统

系统架构

1. 动画状态机 (frontend/src/utils/animationStateMachine.ts)

2. 表情系统 (frontend/src/utils/expressionSystem.ts)

3. 统一3D场景 (frontend/src/components/ThreeSceneAdvanced.tsx)

性能对比

使用示例

📦 3D模型设置

推荐模型资源

1. Sketchfab（最推荐）

2. Poly Pizza

3. Mixamo（带动画）

安装步骤

推荐的动画类型

�📖 API文档

基础操作

AI对话

宠物复刻

智能生成

情绪系统

📁 项目结构

🎨 使用演示

场景1：创建并与宠物互动

场景2：情绪陪伴

场景3：复刻真实宠物

💡 技术特色

vs 传统AI聊天机器人

vs 虚拟宠物游戏

核心优势

📊 性能指标

🤝 贡献指南

开发规范

参与开发

� 3D模型系统

模型加载优先级

推荐模型资源

🐱 猫咪模型

🐶 狗狗模型

下载步骤

文件命名规范

模型优化（可选）

预览和测试

功能介绍

快速设置（5分钟）

1. 获取API密钥

1. 动画状态机 (`frontend/src/utils/animationStateMachine.ts`)

2. 表情系统 (`frontend/src/utils/expressionSystem.ts`)

3. 统一3D场景 (`frontend/src/components/ThreeSceneAdvanced.tsx`)