# 英语句子扩写智能体

> 基于多智能体协作的英语写作教练应用，通过记者提问法将简单英文句子逐步扩写为高级长句

## 📝 项目简介

本项目是一个创新的英语写作学习工具，旨在帮助英语学习者通过系统化的方法提升写作能力。项目采用多智能体协作架构，模拟真实的写作教学场景：

- **解决什么问题？**
  - 英语学习者常面临句子简单、缺乏变化的问题
  - 传统写作练习缺乏系统性的指导和反馈
  - 难以掌握从简单句到复杂句的渐进式扩写技巧

- **有什么特色功能？**
  - 记者提问法：通过三个阶段的针对性提问，引导学生逐步扩写句子
  - 双模式交互：支持手动模式（逐步引导）和自动模式（一键演示）
  - 实时语法点评：智能评估学生提交的句子，提供语法纠错和改进建议
  - 满分润色：基于三轮扩写记录，生成润色后的高级句子和结构分析

- **适用于什么场景？**
  - 英语写作教学和练习
  - 句子扩写技巧学习
  - 语法结构进阶训练
  - 自主学习和教师辅助教学

## ✨ 核心功能

- [x] **手动模式**：逐步引导，逐阶段回答记者提问，适合深度学习
- [x] **自动模式**：一键自动演示全过程，适合快速了解和展示
- [x] **三阶段扩写流程**：
  - Stage 1：增加细节（使用形容词、副词等修饰成分）
  - Stage 2：增加时空背景（使用介词短语补充时间或地点信息）
  - Stage 3：增加结构深度（使用非谓语动词、定语从句或状语从句修饰）
- [x] **智能语法点评**：实时评估语法正确性，提供纠错建议
- [x] **最终润色生成**：基于三轮扩写记录生成满分句子和结构分析
- [x] **SSE流式传输**：自动模式支持实时流式推送，提升用户体验

## 🛠️ 技术栈

### 前端技术
- **Vue 3**：渐进式 JavaScript 框架
- **TypeScript**：类型安全的 JavaScript 超集
- **Vite**：新一代前端构建工具
- **Pinia**：Vue 3 官方状态管理库
- **SSE (Server-Sent Events)**：服务器推送技术，用于自动模式的实时流式传输

### 后端技术
- **FastAPI**：现代、高性能的 Python Web 框架
- **HelloAgents框架**：多智能体协作框架
- **Pydantic**：数据验证和设置管理

### 智能体架构
项目采用多智能体协作范式，包含以下核心 Agent：

1. **OrchestratorAgent（流程调度 Agent）**
   - 负责整体流程调度和状态管理
   - 协调其他 Agent 的协作
   - 决定下一阶段的执行策略

2. **InterviewerAgent（记者提问 Agent）**
   - 扮演记者角色，根据当前阶段生成针对性提问
   - 提供语法结构提示和示范改写
   - 三个阶段各有不同的提问策略

3. **EvaluatorAgent（语法点评 Agent）**
   - 对学生提交的句子进行语法评估
   - 提供详细的点评和纠错建议
   - 判断句子是否符合阶段目标

4. **PolisherAgent（满分润色 Agent）**
   - 接收三轮扩写的完整记录
   - 生成润色后的满分句子
   - 提供语法结构分析和亮点总结

5. **AutoModeAgent（自动演示 Agent）**
   - 自动完成三轮扩写流程
   - 模拟学生回答和智能体反馈
   - 通过 SSE 流式推送进度

## 🚀 快速开始

### 环境要求

- Python 3.10+
- Node.js 16+
- npm 或 yarn

### 后端设置

1. **进入后端目录**
```bash
cd backend
```

2. **创建虚拟环境**
```bash
python -m venv .venv
```

3. **激活虚拟环境**
```bash
# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate
```

4. **安装依赖**
```bash
pip install -r requirements.txt
```

5. **配置环境变量**
```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入你的 API 配置
```

6. **启动后端服务**
```bash
python src/main.py
```

后端服务将在 `http://localhost:8000` 启动

### 前端设置

1. **进入前端目录**
```bash
cd frontend
```

2. **安装依赖**
```bash
npm install
```

3. **配置环境变量**
```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，配置后端 API 地址
# VITE_API_BASE_URL=http://localhost:8000
```

4. **启动开发服务器**
```bash
npm run dev
```

前端应用将在 `http://localhost:3000` 启动（具体端口以终端输出为准）

### 访问应用

打开浏览器访问前端地址，即可开始使用英语句子扩写智能体。

## 📖 使用示例

### 手动模式示例

1. **输入种子句**
   ```
   I like reading.
   ```

2. **选择手动模式并开始**

3. **Stage 1 - 增加细节**
   - 记者提问："你有多喜欢读什么样风格或题材的书籍相关内容呢？"
   - 学生回答："I really like reading science fiction novels."
   - 语法点评："很棒！你在动词like前加了表示程度的副词really，在名词novels前加了复合形容词science fiction，完美符合本阶段添加修饰细节的目标。"

4. **Stage 2 - 增加时空背景**
   - 记者提问："你通常喜欢在什么时候、什么地点读科幻小说呢？"
   - 学生回答："I really like reading science fiction novels in my free time at my home."
   - 语法点评："很好地延续了上阶段对动词和名词的修饰，还精准补充了记者提问中涉及的时间和地点背景，介词短语使用准确。"

5. **Stage 3 - 增加结构深度**
   - 记者提问："你喜欢在家空闲时间读的科幻小说通常有什么吸引人的核心特点，或者你喜欢读这类小说的具体深层原因是什么？"
   - 学生回答："I really like reading science fiction novels in my free time at my home because they stimulate my imagination and take me to new worlds."
   - 语法点评："非常出色！你不仅延续了前两个阶段对动词、名词、时间地点的修饰，还精准添加了记者提问想要的逻辑因果状语从句作为右分支结构，内容紧扣主题。"

### 自动模式示例

1. **输入种子句**
   ```
   She enjoys music.
   ```

2. **选择自动模式并开始**

3. **观看自动演示**
   - 系统自动完成三轮扩写
   - 实时显示每个阶段的提问、回答和点评
   - 最终展示润色后的满分句子

## 🎯 项目亮点

- **多智能体协作架构**：采用专业的多智能体设计，每个 Agent 职责明确，协作高效
- **渐进式学习路径**：三阶段扩写流程符合认知规律，从简单到复杂循序渐进
- **双模式交互设计**：手动模式适合深度学习，自动模式适合快速演示和展示
- **实时反馈机制**：语法点评和错误纠正帮助学生及时发现问题
- **流式用户体验**：SSE 技术实现自动模式的实时推送，交互更加流畅
- **类型安全**：前端使用 TypeScript，后端使用 Pydantic，确保数据类型安全
- **现代化技术栈**：Vue 3 + FastAPI 组合，开发效率和运行性能兼顾

## 🔮 未来计划

- [ ] 持久化存储：将会话数据保存到数据库
- [ ] 用户系统：支持用户注册、登录和历史记录
- [ ] 更多扩写模板：支持不同类型的句子扩写模板
- [ ] 难度分级：根据用户水平调整提问难度

## 📄 许可证

MIT License

## 👤 作者

- GitHub: [@xujikai](https://github.com/xujikai)
- 项目: SentenceExpandAgent

## 🙏 致谢

感谢 Datawhale 社区和 Hello-Agents 项目提供的框架支持！