Merge branch 'master' of https://github.com/LessUp/MetaHuman

# Conflicts:
#	server/app/main.py
#	src/components/BehaviorControlPanel.tsx
#	src/components/DigitalHumanViewer.tsx
#	src/components/VoiceInteractionPanel.tsx
#	src/core/audio/audioService.ts
#	src/core/avatar/DigitalHumanEngine.ts
#	src/core/vision/visionMapper.ts
#	src/core/vision/visionService.ts
#	src/pages/AdvancedDigitalHumanPage.tsx
#	src/pages/DigitalHumanPage.tsx

Author: shijiashuai

.gitignore

@@ -21,4 +21,7 @@ dist-ssr
 *.ntvs*
 *.njsproj
 *.sln
-*.sw?
+*.sw?
+
+__pycache__/
+*.pyc

changelog/2025-11-25-feature-enhancement.md

@@ -0,0 +1,288 @@
+# MetaHuman 功能完善更新
+
+**日期**: 2025-11-25  
+**类型**: 功能增强、逻辑可靠性提升
+
+---
+
+## 概述
+
+本次更新主要针对项目已有功能进行完善，增强逻辑可靠性和产品功能完整性。
+
+---
+
+## 变更详情
+
+### 1. 状态管理增强 (`digitalHumanStore.ts`)
+
+- **新增字段**:
+  - `currentBehavior`: 当前行为状态
+  - `sessionId`: 持久化会话ID（localStorage）
+  - `chatHistory`: 聊天历史记录
+  - `connectionStatus`: 连接状态（connected/connecting/disconnected/error）
+  - `lastErrorTime`: 最后错误时间
+
+- **新增类型定义**:
+  - `EmotionType`: 情感类型枚举
+  - `ExpressionType`: 表情类型枚举
+  - `BehaviorType`: 行为类型枚举
+  - `ConnectionStatus`: 连接状态枚举
+
+- **新增方法**:
+  - `setBehavior()`: 设置行为状态
+  - `setConnectionStatus()`: 设置连接状态
+  - `clearError()`: 清除错误
+  - `initSession()`: 初始化新会话
+  - `addChatMessage()`: 添加聊天消息
+  - `clearChatHistory()`: 清除聊天历史
+
+---
+
+### 2. 语音服务重构 (`audioService.ts`)
+
+#### TTSService 增强
+- 添加配置接口 `TTSConfig`
+- `speak()` 方法改为 Promise 接口
+- 自动同步行为状态（speaking/idle）
+- 添加 `pause()`/`resume()` 方法
+- 改进语音选择逻辑
+
+#### ASRService 重构
+- 添加回调接口 `ASRCallbacks`
+- 添加配置接口 `ASRConfig`
+- **整合对话服务**: 语音识别结果自动发送到后端
+- 本地命令优先处理（播放、暂停、重置等）
+- 改进错误消息（中文友好提示）
+- 新增预设动作方法:
+  - `performGreeting()`: 打招呼
+  - `performDance()`: 跳舞
+  - `performNod()`: 点头
+  - `performShakeHead()`: 摇头
+  - `performThinking()`: 思考
+
+---
+
+### 3. 对话服务增强 (`dialogueService.ts`)
+
+- **重试机制**: 最多3次重试，指数退避
+- **超时处理**: 15秒请求超时
+- **降级响应**: 服务不可用时返回本地响应
+- **连接状态管理**: 自动更新 store 中的连接状态
+- **错误类**: `DialogueApiError` 带状态码和可重试标志
+- **健康检查**: `checkServerHealth()` 函数
+
+---
+
+### 4. 数字人引擎增强 (`DigitalHumanEngine.ts`)
+
+- 添加类型验证（表情、情感、行为）
+- 情感与表情自动映射
+- 动作自动恢复到 idle 状态
+- 新增组合动作方法:
+  - `performGreeting()`
+  - `performThinking()`
+  - `performListening()`
+
+---
+
+### 5. 视觉服务增强 (`visionService.ts`)
+
+- 状态管理: `VisionStatus` 类型
+- FPS 计算
+- 摄像头权限检查
+- 详细错误消息（权限拒绝、设备未找到等）
+- 回调接口: `VisionServiceCallbacks`
+- 新增方法: `getStatus()`, `getFps()`, `isRunning()`
+
+---
+
+### 6. 页面逻辑完善 (`AdvancedDigitalHumanPage.tsx`)
+
+- 使用 store 的 `chatHistory` 替代本地状态
+- 使用 store 的 `sessionId`
+- 服务器连接状态检查（启动时和定期检查）
+- 错误自动清除（5秒后）
+- HUD 显示连接状态、行为状态、会话数量
+- 重新连接按钮
+- 输入框状态反馈（加载中、录音中）
+- 错误提示条
+- **Quick Actions 实现**: 打招呼、跳舞、说话、表情
+
+---
+
+### 7. 后端增强 (`server/app/main.py`)
+
+- CORS 中间件配置
+- 增强的健康检查端点（返回运行时间、服务状态）
+- 根路径信息端点
+
+---
+
+## 文件变更列表
+
+| 文件 | 变更类型 |
+|------|----------|
+| `src/store/digitalHumanStore.ts` | 重构 |
+| `src/core/audio/audioService.ts` | 重构 |
+| `src/core/dialogue/dialogueService.ts` | 重构 |
+| `src/core/avatar/DigitalHumanEngine.ts` | 重构 |
+| `src/core/vision/visionService.ts` | 增强 |
+| `src/pages/AdvancedDigitalHumanPage.tsx` | 增强 |
+| `server/app/main.py` | 增强 |
+
+---
+
+## 测试建议
+
+1. **语音交互测试**:
+   - 测试语音识别是否正确发送到后端
+   - 测试本地命令（"打招呼"、"跳舞"等）
+   - 测试静音状态下的行为
+
+2. **错误处理测试**:
+   - 关闭后端测试离线模式
+   - 测试网络超时情况
+   - 测试摄像头权限拒绝
+
+3. **状态同步测试**:
+   - 验证会话ID持久化
+   - 验证聊天历史保持
+   - 验证连接状态显示
+
+---
+
+## 自动检查修复 (第二轮)
+
+### 修复内容
+
+1. **DigitalHumanPage.tsx**
+   - 移除所有 `console.log` 调试语句
+   - 移除 `alert()` 调用，改用 toast 提示
+   - 移除测试按钮
+   - 实现 `handleVoiceCommand` 真正功能
+   - 集成 `connectionStatus` 状态显示
+
+2. **BehaviorControlPanel.tsx**
+   - 移除未使用的 `learningRate` 变量
+   - 移除未使用的 `setDecisionInterval`
+
+3. **ExpressionControlPanel.tsx**
+   - 移除未使用的 `customColor` 变量
+
+4. **VoiceInteractionPanel.tsx**
+   - 移除 `console.log` 调试语句
+   - 集成 `useDigitalHumanStore` 状态同步
+   - 语音状态与全局 store 同步
+
+5. **digitalHumanStore.ts**
+   - 移除所有 `console.log` 调试语句
+   - 录音超时从 10 秒改为 30 秒
+
+---
+
+## 功能完善 (第三轮)
+
+### 1. ControlPanel 系统状态显示
+
+- **问题**: Diagnostics 部分使用硬编码值
+- **修复**: 
+  - 连接状态从 store 实时获取
+  - 显示当前行为状态
+  - 显示语音引擎状态
+  - 显示录音状态
+
+### 2. visionMapper 情感识别增强
+
+- **新增情感**: `sad`（悲伤）、`angry`（愤怒）
+- **改进算法**:
+  - 添加眼睛开合度检测
+  - 添加眉毛位置检测
+  - 添加嘴角上扬/下拉检测
+- **新增调试函数**: `analyzeFaceFeatures()` 用于调试
+
+### 3. 键盘快捷键支持
+
+| 快捷键 | 功能 |
+|--------|------|
+| `空格` | 播放/暂停 |
+| `R` | 重置 |
+| `M` | 静音切换 |
+| `V` | 录音切换 |
+| `S` | 设置面板 |
+| `ESC` | 关闭设置 |
+| `1` | 打招呼 |
+| `2` | 跳舞 |
+| `3` | 说话 |
+| `4` | 表情 |
+
+### 4. 后端对话服务增强
+
+- **会话历史管理**: 自动保存和加载会话历史
+- **智能 Mock 回复**: 根据用户输入生成合理的本地回复
+- **LLM 上下文**: 将历史对话作为 LLM 上下文
+- **新增 API**:
+  - `clear_session()`: 清除会话历史
+  - `get_session_history()`: 获取会话历史
+
+---
+
+## 用户体验增强 (第四轮)
+
+### 1. VisionMirrorPanel 增强
+
+- **情感颜色映射**: 5种情感对应不同颜色
+- **情感标签**: 中文+emoji显示
+- **加载状态**: 启动摄像头时显示加载动画
+- **错误处理**: 摄像头启动失败时显示友好提示
+- **FPS 显示**: 实时显示处理帧率
+- **可访问性**: 添加 `aria-label`
+
+### 2. 新增 UI 组件
+
+#### LoadingSpinner (`/components/ui/LoadingSpinner.tsx`)
+- 支持三种尺寸: `sm`/`md`/`lg`
+- 支持自定义文本
+- 支持全屏遮罩模式
+
+#### ErrorBoundary (`/components/ui/ErrorBoundary.tsx`)
+- 捕获组件渲染错误
+- 显示友好的错误界面
+- 支持重试和刷新操作
+- 开发环境显示详细堆栈
+
+### 3. 新增 Hooks
+
+#### useTouch (`/hooks/useTouch.ts`)
+- 滑动检测 (左/右/上/下)
+- 点击和双击检测
+- 长按检测
+- 可配置阈值
+
+### 4. App 架构优化
+
+- **懒加载**: 页面组件使用 `React.lazy()` 按需加载
+- **错误边界**: 全局错误捕获和恢复
+- **加载状态**: 页面切换时显示加载动画
+
+### 文件新增/变更
+
+| 文件 | 类型 |
+|------|------|
+| `src/components/ui/LoadingSpinner.tsx` | 新增 |
+| `src/components/ui/ErrorBoundary.tsx` | 新增 |
+| `src/components/ui/index.ts` | 新增 |
+| `src/hooks/useTouch.ts` | 新增 |
+| `src/components/VisionMirrorPanel.tsx` | 增强 |
+| `src/App.tsx` | 重构 |
+
+---
+
+## 后续优化建议
+
+1. 添加会话历史导出功能
+2. 实现流式对话响应
+3. 添加更多预设动作和表情
+4. 优化 3D 模型动画系统
+5. 添加用户设置持久化
+6. 增加更专业的数字人模型
+7. PWA 离线支持