WordPecker App 核心功能实践指南

搭建开发环境：准备工作区

如何确保开发环境满足项目运行要求？在开始使用WordPecker前，需完成环境检查与代码获取两大前置步骤，为后续开发奠定基础。

环境兼容性验证

WordPecker作为现代化语言学习工具，对运行环境有特定要求。请执行以下命令检查系统配置：

node -v && npm -v && docker --version && docker-compose --version

环境要求：

• Node.js ≥ 16.0.0
• npm ≥ 7.0.0
• Docker ≥ 20.10.0
• Docker Compose ≥ 2.0.0

🔧 操作提示：若版本不满足要求，建议使用nvm管理Node.js版本，通过官方文档安装最新版Docker。

获取项目代码

使用Git工具克隆项目仓库到本地工作目录：

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

⚠️ 安全注意事项：克隆操作仅需公开网络访问权限，无需提供个人认证信息。

功能模块解析：核心组件架构

WordPecker的功能实现依赖于前后端分离的架构设计，各模块协同工作提供完整的语言学习体验。核心目录的功能定位如下：

后端服务层

backend/目录包含Node.js服务端实现，采用TypeScript开发，主要组件包括：

• 业务逻辑核心：src/agents/目录下的各类AI代理模块，如vocabulary-agent（词汇处理）、quiz-agent（测验生成）等，通过LLM技术实现智能学习功能
• API接口层：src/api/目录定义了RESTful接口，处理客户端请求并返回标准化响应
• 数据访问层：src/models/目录封装了数据库交互逻辑，支持词汇数据的持久化存储

原理简述：采用代理模式设计，将不同学习功能解耦为独立Agent，通过统一接口协调工作。

前端应用层

frontend/目录包含React单页应用，采用TypeScript+Vite构建，关键模块包括：

• 用户界面组件：src/components/目录下的可复用UI元素，如QuestionRenderer（题目渲染器）、AudioPlayer（音频播放器）等
• 页面路由：src/pages/目录定义了应用的主要视图，如Learn.tsx（学习页面）、Quiz.tsx（测验页面）等
• 状态管理：通过React Context API实现全局状态共享，管理用户学习进度与偏好设置

启动操作流程：系统部署与运行

如何正确启动WordPecker应用？完整的启动流程包括环境配置、依赖安装和服务启停三个关键阶段。

配置环境变量

环境变量是连接应用组件的关键配置，需在前后端目录分别创建.env文件。

后端配置（backend/.env）：

参数名称	默认值	推荐值	作用描述
PORT	3000	3000	API服务监听端口
OPENAI_API_KEY	空	个人API密钥	用于调用OpenAI服务
MONGODB_URI	mongodb://localhost:27017/wordpecker	同默认值	数据库连接地址

前端配置（frontend/.env）：

参数名称	默认值	推荐值	作用描述
VITE_API_URL	http://localhost:3000	同默认值	后端API基础地址
VITE_LANGUAGE_DEFAULT	en	zh-CN	默认显示语言

⚠️ 安全警示：OPENAI_API_KEY等敏感信息绝不能提交到代码仓库，已在.gitignore中配置忽略规则。

安装项目依赖

分别在前后端目录执行依赖安装命令：

# 安装后端依赖
cd backend
npm ci

# 安装前端依赖
cd ../frontend
npm ci

🔧 操作提示：使用npm ci而非npm install可确保依赖版本与package-lock.json完全一致，避免版本冲突。

启动服务集群

项目支持两种启动模式，可根据需求选择：

开发模式：

# 启动后端开发服务
cd backend
npm run dev

# 启动前端开发服务（新终端）
cd frontend
npm run dev

容器化模式：

# 启动所有服务（包含数据库）
docker-compose up -d

原理简述：开发模式使用nodemon实现热重载，容器化模式通过Docker Compose编排多服务协同。

核心功能实践：学习流程演示

WordPecker提供多种个性化学习功能，以下是三个核心场景的操作指南。

创建词汇学习列表

如何组织自己的词汇学习内容？通过"词汇树"功能可以创建主题化学习集合。

操作步骤：

1. 点击"Plant a New Tree"按钮
2. 输入列表名称和描述信息
3. 添加相关词汇（支持批量导入）
4. 选择"Learn"开始学习或"Quiz"进行测验

交互式单词学习

如何高效掌握新词汇？应用提供多样化的练习形式强化记忆。

核心功能：

• 上下文理解题：通过情境选择正确解释
• 发音练习：点击音频图标听取标准发音
• 进度追踪：顶部进度条显示学习完成度
• 得分系统：根据答题情况实时更新分数

🔧 操作提示：遇到困难可点击"Show Hint"获取提示，每天练习20分钟效果最佳。

语音对话练习

如何提升口语能力？语音助手功能提供沉浸式对话体验。

使用方法：

1. 点击"Start Conversation"按钮
2. 授予麦克风访问权限
3. 根据提示进行语音交互
4. 系统实时反馈发音准确度

原理简述：基于WebRTC技术实现实时语音处理，结合LLM生成上下文相关对话内容。

系统配置详解：参数优化与安全

深入了解关键配置项，可根据个人需求优化系统性能与使用体验。

语言偏好设置

如何定制适合自己的语言学习环境？在设置页面可配置多语言参数。

配置选项：

• 母语选择：影响解释内容的语言
• 目标语言：设置学习的语言种类
• 变体支持：可指定地区变体（如美式英语、巴西葡萄牙语）

🔧 操作提示：更改设置后，新的词汇和练习将立即应用新配置，但历史数据保持不变。

API服务配置

backend/src/config/openai.ts文件控制AI服务参数，关键配置包括：

// 默认配置示例
export const openaiConfig = {
  model: 'gpt-3.5-turbo',
  temperature: 0.7,
  maxTokens: 1000,
  timeout: 30000
};

优化建议：

• 学习场景：temperature=0.3（更准确的解释）
• 创作场景：temperature=0.8（更多样化的内容）
• 长文本处理：maxTokens=2000（增加上下文容量）

⚠️ 安全警示：调整API参数可能影响服务费用，请监控使用量避免超额支出。

数据存储配置

MongoDB连接参数位于backend/src/config/mongodb.ts，生产环境建议配置：

// 生产环境配置示例
export const mongoConfig = {
  uri: process.env.MONGODB_URI || 'mongodb://localhost:27017/wordpecker',
  options: {
    authSource: 'admin',
    retryWrites: true,
    w: 'majority'
  }
};

原理简述：通过write concern配置确保数据写入安全，retryWrites提高容错能力。

故障排除指南：常见问题解决

使用过程中遇到问题？以下是典型场景的解决方案。

服务启动失败

若后端服务启动时报错，按以下步骤排查：

1. 检查MongoDB是否正常运行：docker-compose ps
2. 验证环境变量完整性：cat backend/.env
3. 查看错误日志：npm run dev 2> error.log

API请求错误

前端调用API失败时：

1. 确认后端服务状态：访问http://localhost:3000/health
2. 检查跨域配置：查看backend/src/app.ts中的CORS设置
3. 网络代理问题：尝试直接访问API端点排除代理干扰

🔧 操作提示：开发环境可使用浏览器DevTools的Network面板查看请求详情。

数据同步问题

词汇数据未正确保存时：

1. 检查数据库连接：mongo mongodb://localhost:27017/wordpecker
2. 验证用户权限：确认数据库用户有读写权限
3. 查看同步日志：backend/logs/sync.log

通过以上指南，您应该能够顺利搭建、配置并使用WordPecker应用进行个性化语言学习。根据学习进度，可定期调整配置参数优化学习体验。