沉浸式物理课堂 - AI 数字人辅导系统

基于 AI 大模型和数字人技术的高中物理互动教学平台，提供沉浸式的一对一辅导体验。

功能特性

• AI 特级教师 - 基于 Google Gemini 大模型，模拟 20 年教龄的物理特级教师"李老师"
• 黑板优先 - 讲解与板书分离，黑板只保留关键公式、图像与步骤要点
• 结构化讲解 - 每步输出包含 [SPEECH] + [BLACKBOARD]，保证教学连贯
• 可视化示意 - 支持斜面/受力/坐标系等物理图像与公式渲染
• 数字人悬浮 - 数字人悬浮在黑板上方，不遮挡主要内容（可选）
• 分步讲解 - 将复杂题目拆解为小步骤，循序渐进讲解
• 随时打断 - 支持学生随时提问追问，AI 会暂停主线优先解答
• 全册覆盖 - 涵盖高中物理必修一至选修全部章节

技术栈

• 前端框架: React 19 + TypeScript
• 构建工具: Vite 7
• 样式方案: TailwindCSS 4
• 路由管理: React Router 7
• AI 服务: Google Gemini API
• 数字人: 魔珐星云 XmovAvatar SDK

快速开始

环境要求

• Node.js 18+
• pnpm / npm / yarn

安装依赖

pnpm install

配置环境变量

复制 .env.example 为 .env 并填入 API 密钥：

cp .env.example .env

编辑 .env 文件：

# Gemini AI API 密钥 (必需)
# 从 https://aistudio.google.com/app/apikey 获取
VITE_GEMINI_API_KEY=your_gemini_api_key_here

# 魔珐星云数字人配置 (可选，不配置则显示占位头像)
# 从 https://xingyun3d.com/ 获取
VITE_XMOV_APP_ID=your_xmov_app_id_here
VITE_XMOV_APP_SECRET=your_xmov_app_secret_here

# 调试模式
VITE_DEBUG_MODE=false

启动开发服务器

pnpm dev

访问 http://localhost:3000

构建生产版本

pnpm build

项目结构

src/
├── components/
│   ├── GlobalAvatar.tsx    # 全局数字人组件
│   ├── DigitalHuman.tsx    # 数字人容器与语音控制
│   ├── Blackboard.tsx      # 板书显示区
│   ├── ChatInterface.tsx   # 聊天交互界面
│   ├── PhysicsCanvas.tsx   # 物理示意图绘制
│   └── Layout.tsx          # 页面布局
├── services/
│   └── gemini.ts           # Gemini API 服务
├── data/
│   └── physicsKnowledge.json  # 物理知识库
├── App.tsx                 # 主应用组件
├── main.tsx                # 入口文件
└── App.css                 # 全局样式

使用说明

1. 在首页选择章节和题目
2. 进入课堂后，AI 老师会自动开始讲解
3. 黑板为主视图，展示当前步骤的公式与图像；右侧对话用于追问与讲解记录
4. 点击「继续」进入下一步讲解
5. 点击「听不懂，换个说法」让老师用更通俗的方式解释
6. 点击「跳过这一段」跳过当前步骤
7. 在输入框中输入问题随时追问

教学输出规范（开发）

课程回复需包含以下结构，便于黑板与讲解分离：

[STEP: 1/5]
[SPEECH]
...讲解内容...
[BLACKBOARD]
- 要点或条件
[DIAGRAM: incline_with_blocks]
[EQUATION: F = ma]

课程内容

教材	章节数	内容概述
必修一	4 章	运动描述、匀变速运动、相互作用、牛顿运动定律
必修二	3 章	曲线运动、万有引力、机械能守恒
必修三	2 章	静电场、恒定电流
选修一	2 章	磁场、电磁感应
选修二	2 章	交变电流、传感器
选修三	2 章	光学、原子物理

开发命令

pnpm dev      # 启动开发服务器
pnpm build    # 构建生产版本
pnpm preview  # 预览生产构建
pnpm lint     # 代码检查

License

MIT