WordPecker：个性化语言学习工具全攻略

WordPecker是一款融合Duolingo式互动学习与自定义词汇管理的个性化语言学习工具。用户可从书籍、文章或视频中收集词汇，并通过交互式测验和AI生成课程巩固记忆，实现高效语言能力提升。

一、功能模块解析

1.1 核心学习系统

智能词汇管理
支持用户创建个性化词汇列表，可从各类资源中添加生词，系统自动生成释义、例句及发音。核心数据模板路径：backend/data/templates/，包含学术研究、商业金融等19个领域的专业词汇库。

交互式学习模块
提供多样化练习形式，包括选择题、填空题和匹配题等。学习界面实时显示进度条、连续学习 streak 和得分情况，通过游戏化设计提升学习动力。

1.2 内容生成引擎

AI辅助学习内容
基于LLM（大语言模型）技术，自动生成与用户词汇相关的练习题和阅读材料。核心实现路径：backend/src/agents/，包含词汇、测验、例句等多个专业Agent。

多媒体整合
支持图片分析和语音交互功能，可通过图像描述生成相关词汇学习内容，或通过语音对话练习口语。语音功能模块路径：frontend/src/agents/voice-agent/。

1.3 个性化配置中心

多语言支持
提供多语言学习环境，用户可在设置中切换目标语言。语言配置文件路径：backend/src/config/languages.ts。

学习偏好设置
允许用户自定义练习类型、难度级别和学习提醒。相关界面截图：docs/assets/settings-exercise_types.png。

二、环境配置

2.1 配置概述

配置文件用于定义项目运行所需的环境变量和服务参数，确保前后端服务正确连接外部API和数据库。所有配置文件均需在项目启动前完成设置。

2.2 开发环境配置

后端核心配置
路径：backend/.env
关键参数：

• PORT：后端服务端口（默认3000）
• OPENAI_API_KEY：OpenAI API密钥（用于AI功能）
• MONGODB_URI：MongoDB数据库连接地址

前端核心配置
路径：frontend/.env
关键参数：

• VITE_API_URL：后端API基础地址（如http://localhost:3000）
• VITE_SUPABASE_URL：Supabase服务地址（用于用户数据存储）

2.3 生产环境配置

生产环境需额外配置：

• 启用HTTPS协议
• 设置适当的API请求频率限制
• 配置数据库备份策略
• 启用错误日志收集

三、启动流程

3.1 准备工作

1. 克隆项目仓库

   git clone https://gitcode.com/gh_mirrors/wo/wordpecker-app
   cd wordpecker-app
   

   预期结果：项目代码成功下载到本地

2. 安装依赖

   # 安装后端依赖
   cd backend && npm install
   # 安装前端依赖
   cd ../frontend && npm install
   

   预期结果：node_modules目录生成，依赖包安装完成

3.2 启动后端服务

1. 配置环境变量
   复制示例配置文件并修改：

   cd backend
   cp .env.example .env
   # 编辑.env文件设置必要参数
   

   预期结果：.env文件包含正确配置信息

2. 启动开发服务器

   npm run dev
   

   预期结果：终端显示"Server running on port XXXX"，服务启动成功

3.3 启动前端服务

1. 配置环境变量

   cd frontend
   cp .env.example .env
   # 设置VITE_API_URL指向后端服务地址
   

   预期结果：前端配置文件正确指向后端API

2. 启动开发服务器

   npm run dev
   

   预期结果：浏览器自动打开http://localhost:5173，显示应用首页

3.4 验证服务可用性

访问前端页面后，尝试：

1. 创建新词汇列表
2. 添加测试词汇
3. 进入学习模式

预期结果：所有功能正常响应，无错误提示

四、进阶使用提示

• 数据迁移：使用backend/src/scripts/migrateWords.ts脚本可批量导入词汇
• 模板扩展：在backend/data/templates/目录添加自定义领域模板
• 性能优化：生产环境建议使用Docker Compose部署，配置文件：docker-compose.yml

通过以上步骤，您已完成WordPecker的环境配置和启动。开始创建您的个性化词汇库，体验AI驱动的高效语言学习之旅吧！ 🚀