分享一个我做的小项目：MathWhiz-Junior

最近闲着无聊，搞了个给小朋友学数学的小应用，分享一些心得和功能

初衷其实很简单

看到现在很多小朋友学数学还是靠背乘法表、做练习册，总感觉有点枯燥。我小时候学数学也觉得挺没意思的，直到后来发现数学其实挺好玩的。就想着能不能做个东西，让数学学习稍微有趣一点？

于是就有了这个MathWhiz-Junior，纯粹是个人兴趣做的小项目，没什么宏大目标，就是想试试用游戏化的方式让数学学习不那么无聊。

技术栈选择

做这个项目主要用了以下技术：

- React + TypeScript - 前端框架
- Tailwind CSS - UI样式库
- Gemini API - AI功能实现
- Vite - 构建工具

项目结构概览

项目的整体结构比较简单，主要分为以下几个部分：

mathwhiz-junior/
├── components/       # 组件
│   ├── MathGame.tsx  # 数学游戏组件
│   ├── VoiceTutor.tsx # 语音老师组件
│   └── MathFacts.tsx # 数学侦探组件
├── services/         # 服务
│   └── gemini.ts     # Gemini API服务
├── App.tsx           # 主应用
└── types.ts          # TypeScript类型定义

核心设计思路

1. 应用状态管理

整个应用的状态管理非常简单，就是用React的useState和useEffect来管理。下面是App.tsx的核心代码：

import React, { useState, useEffect } from 'react';
import { Menu } from './components/Menu';
import { LoginScreen } from './components/LoginScreen';
import { MathGame } from './components/MathGame';
import { VoiceTutor } from './components/VoiceTutor';
import { MathFacts } from './components/MathFacts';
import { ResultScreen } from './components/ResultScreen';
import { AppScreen, GameResult, User } from './types';
import { getCurrentUser, logoutUser } from './services/auth';

function App() {
  const [currentScreen, setCurrentScreen] = useState<AppScreen>(AppScreen.LOGIN);
  const [lastResult, setLastResult] = useState<GameResult | null>(null);
  const [user, setUser] = useState<User | null>(null);

  // 根据不同的屏幕状态渲染不同的组件
  const renderScreen = () => {
    switch (currentScreen) {
      case AppScreen.LOGIN:
        return <LoginScreen onLoginSuccess={handleLoginSuccess} />;
      case AppScreen.MENU:
        return <Menu onSelectMath={() => setCurrentScreen(AppScreen.GAME_MATH)} />;
      case AppScreen.GAME_MATH:
        return <MathGame onBack={() => setCurrentScreen(AppScreen.MENU)} onFinish={handleFinishGame} />;
      case AppScreen.GAME_VOICE:
        return <VoiceTutor onBack={() => setCurrentScreen(AppScreen.MENU)} />;
      case AppScreen.GAME_FACTS:
        return <MathFacts onBack={() => setCurrentScreen(AppScreen.MENU)} />;
      // ... 其他屏幕
    }
  };
  
  return (
    <div className="antialiased text-slate-800">
      {renderScreen()}
    </div>
  );
}

2. 游戏界面设计

数学游戏的界面设计考虑了小朋友的使用习惯，使用了鲜艳的颜色和大按钮，让操作变得简单直观：

3. AI功能集成

项目中最有趣的部分就是集成了Gemini API来实现语音老师和数学侦探功能。下面是gemini.ts中连接语音老师的核心代码：

export const connectToVoiceTutor = async (
  onAudioData: (base64: string) => void,
  onClose: () => void
) => {
  // 创建音频上下文
  const inputAudioContext = new (window.AudioContext)({ sampleRate: 16000 });
  
  // 获取麦克风权限
  try {
    stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  } catch (err) {
    console.error("麦克风访问失败", err);
    onClose();
    return null;
  }

  // 连接Gemini Live API
  const sessionPromise = ai.live.connect({
    model: 'gemini-2.5-flash-native-audio-preview-09-2025',
    callbacks: {
      onopen: () => {
        // 设置麦克风流
        const source = inputAudioContext.createMediaStreamSource(stream!);
        // ... 音频处理逻辑
      },
      onmessage: async (message) => {
        // 处理AI返回的音频数据
        const audioData = message.serverContent?.modelTurn?.parts?.[0]?.inlineData?.data;
        if (audioData) {
          onAudioData(audioData);
        }
      },
    },
    config: {
      // 设置AI角色为数学老师
      systemInstruction: `
        你是一位友好、精力充沛的小学数学老师，名叫"香蕉老师"。
        你的目标是和学生一起练习"口算"。
        // ... 更多指导
      `
    }
  });
  
  return { disconnect: () => {/* 断开连接逻辑 */} };
};

主要做了三个功能

1. 数学游戏挑战

就是限时答题小游戏，分三个年级难度，加减乘除四种运算可以选。有计时器、计分板，做完后会显示这次练习的结果。

游戏的题目生成逻辑如下：

const generateQuestion = (cfg: GameConfig, id: number): Question => {
  let n1 = 0, n2 = 0, ans = 0;
  const limit = cfg.difficulty * 10;
  
  switch (cfg.operation) {
    case MathOperation.ADD:
      n1 = Math.floor(Math.random() * limit) + 1;
      n2 = Math.floor(Math.random() * limit) + 1;
      ans = n1 + n2;
      break;
    case MathOperation.SUBTRACT:
      n1 = Math.floor(Math.random() * limit) + 5;
      n2 = Math.floor(Math.random() * n1); // 确保结果为正数
      ans = n1 - n2;
      break;
    // ... 其他运算类型
  }
  return { id, num1: n1, num2: n2, operation: cfg.operation, answer: ans };
};

2. AI语音老师

这个是我觉得最有意思的部分！用了Gemini的API做了个语音交互功能，小朋友可以直接对着麦克风问数学问题，或者回答老师出的题目。

[外链图片转存中…(img-6NvM0t2R-1765801918428)]

3. 数学侦探

类似于一个数学小百科，小朋友有什么奇奇怪怪的数学问题都可以在这里提问，系统会尽量用简单的语言回答。

一些不足和未来想法

• 现在功能还比较简单，以后可能会加更多游戏模式
• 语音识别有时候不太准确，特别是小朋友说话不太清楚的时候
• 可以考虑加一些成就系统，让小朋友更有成就感
• 如果有人用的话，再考虑做个家长端，可以看到孩子的学习情况

结语

总的来说，这就是个我利用业余时间做的小项目，主要是想尝试把游戏化和AI技术结合到教育中。做得还比较粗糙，但自己觉得挺有意思的。如果有对这方面感兴趣的朋友，欢迎一起讨论交流！

下一篇文章我会详细说说这三个功能模块是怎么做的，感兴趣的可以看看。

继续阅读：MathWhiz-Junior的功能模块详解