🎤 Spoken English 智能口语评估台

极致响应、专业排版的英语口语与语法深度纠错平台。

Spoken English 是一个专为英语学习者打造的 “全能型口语私教” 项目。它不仅仅是一个前端页面，更包含了基于 Python FastAPI 和大语言模型（如 Google Gemini）的后端支持。本项目创新性地引入了 “深度长难句剖析” 理念，将用户的每一句口语输出都当做精读材料进行拆解，提供信达雅翻译、意群拆分、语法骨架分析等专家级辅导。

---

✨ 核心功能 (Features)

1. 🎙️ 极简录音与双端通信：浏览器原生麦克风录制，无缝传输至后端 API。
2. 🎨 细粒度高亮纠错：精准色彩标注（发音、用词、语法、漏词、冗余、语气词等）。
3. 🧠 专家级深度剖析：
   • 完整翻译 (Translation)
   • 意群拆分 (Semantic Chunking)
   • 重点词汇 (Key Vocabulary)
   • 语法骨架 (Syntax Analysis)
   • 导师小结 (Mentor's Summary)
4. 🖥️ 双栏工作台布局：左侧控制台全局悬浮，右侧超高密度报告网格排版。

---

🚀 极速部署与运行 (Quick Start)

为了照顾所有新手开发者，我们提供了一键启动脚本，它可以自动为您配置 Python 虚拟环境、安装前后端依赖库，并同时启动所有服务。

环境要求 (Prerequisites)

运行本项目前，请确保您的电脑已经安装了：

• Node.js (推荐 v18+ 版本)
• Python (推荐 v3.9+ 版本)

第一步：克隆项目

git clone https://github.com/yuuniji/Spoken_English.git
cd Spoken_English

第二步：配置环境变量 (API Key)

在对接真实大模型之前，您需要在 backend 目录下创建一个 .env 文件，并填入您的 API 密钥：

cd backend
touch .env

在 .env 文件中写入（示例）：

GEMINI_API_KEY=your_api_key_here

第三步：一键启动项目 (One-Click Start)

回到项目根目录，赋予脚本执行权限并运行：

# 赋予执行权限（Mac/Linux 仅需执行一次）
chmod +x start.sh

# 一键启动前后端服务！
./start.sh

🪄 这个脚本做了什么？

1. 它会自动在 backend/venv 创建 Python 虚拟环境，并安装 fastapi, uvicorn, google-genai 等后端依赖。
2. 它会自动在 frontend 目录执行 npm install 下载前端依赖。
3. 它会在后台同时启动 FastAPI (8000端口) 和 Vite (5173端口)。
4. 当您按下 Ctrl+C 时，它会优雅地同时关闭前后端服务。

启动成功后，打开浏览器访问：http://localhost:5173 即可开始体验！

---

📂 核心代码架构 (Architecture)

本项目采用了经典的前后端分离架构 (Frontend + Backend)：

Spoken_English/
├── start.sh                # 🚀 极其重要的【一键启动脚本】
├── backend/                # 🐍 Python 后端目录
│   ├── main.py             # FastAPI 服务入口及路由
│   ├── requirements.txt    # (如有) 后端依赖清单
│   └── venv/               # (自动生成) 虚拟环境
└── frontend/               # ⚛️ React 前端目录
    ├── src/
    │   ├── components/     # UI 组件 (AudioRecorder, FeedbackReport 等)
    │   ├── App.tsx         # 前端根路由与页面结构
    │   └── types.ts        # 全局 TypeScript 接口规范
    └── package.json        # 前端依赖清单

---

💡 主要使用场景 (Scenarios)

• 雅思/托福口语备考：精准揪出时态错误，并通过意群拆分纠正考生的断句节奏。
• 商务英语模拟：通过深度的词汇替换和信达雅翻译，将口语化的表达转化为专业商务句式。
• 日常长难句造句训练：输入复杂的复合句，验证自身的语法骨架是否正确。

---

🛠️ 手动分步运行 (Manual Setup)

如果您不喜欢一键脚本，也可以手动启动：

启动后端：

cd backend
python3 -m venv venv
source venv/bin/activate
pip install fastapi uvicorn python-multipart python-dotenv google-genai
uvicorn main:app --reload --port 8000

启动前端：

cd frontend
npm install
npm run dev