用 AI 构建个性化学习工具案例

每个词都有故事。

一个个性化的语言学习应用，将 Duolingo 风格课程的魔力带到你自己精心策划的词汇表和上下文中。

📱 正在寻找移动应用测试者！

我们已经开始开发项目的移动版本 🚀 目前我们正处于测试阶段，正在寻找测试者来尝试该应用并分享反馈。

如果你想成为测试者：📩 给 [info@wordpeckerapp.com] 发送电子邮件，主题为"Tester Application"。

在你的电子邮件中，请包括：

关于你自己的简短说明

你的反馈将帮助我们让应用变得更好 💡 感谢你的支持！❤️

快速开始 前置条件 安装 数据库设置 配置 开发

Docker 设置（推荐） Docker 快速开始 Docker 命令 MongoDB 访问 仅使用 Docker 运行 MongoDB 简易启动脚本 故障排除

Docker 快速开始

仅运行 MongoDB

🐳 Docker（推荐）：Docker 快速开始

💻 本地开发：手动安装

🗄️ 仅 MongoDB：仅运行 MongoDB

学习一门新语言可以很直接，但掌握它才是真正的挑战。虽然掌握基础知识相对容易，但培养强大的沟通或阅读能力取决于拥有扎实的词汇量。为了做到这一点，你必须在各个水平上学习单词和短语，但接触是关键。例如，如果你学过英语但不住在英语国家，进步会变得明显困难。你可以读书、看电影或浏览博客，但完全沉浸在语言中仍然很困难。真正的进步往往需要额外的努力——学习和重新审视你日常生活中遇到的单词和短语。

但是，这个过程可能很不方便。你必须停下正在做的事来记录新单词，搜索它们的含义，记录它们，然后稍后复习。这既耗时又令人疲倦。因此，虽然你可能会有所改进，但学习过程会感到令人沮丧地缓慢和低效。

为了解决这个问题，我有了一个应用的想法，它将个性化学习与闪卡的效率相融合——Duolingo 风格课程和自定义学习列表的混合体。

在之前的版本中，你会读你的书，遇到新单词，创建一个列表，手动添加每个单词，然后练习。你会打开应用，创建一个新列表并输入详细信息，如"哈利波特书"，添加你找到的单词，应用会提供含义，这样你就可以继续阅读而不会中断。之后你会用练习和测验来复习。这在你积极阅读或消费内容时效果很好，但当你只是想随时随地扩展词汇时怎么办？

但这里变得令人兴奋——我们添加了一个新功能来发现和遇到新单词。与其手动寻找词汇，你现在可以更自然地遇到单词，工作量少得多：

🌳 视觉花园（我的个人最爱！）

想象查看图像并描述它们来发现新词汇。你可以使用 LLM 生成的图像或真实的库存照片，描述你所看到的内容，AI 智能体分析你的描述，建议你可能不知道的上下文相关词汇。这就像有一个个人导师，向你展示图片并帮助你自然地扩展词汇。AI 智能体会考虑你当前的词汇并建议适合你学习水平和上下文的单词。

📚 获取新单词 - 智能词汇发现

选择你感兴趣的任何上下文或话题（如"太空探索"或"烹饪技巧"），选择你的难度等级，让 AI 智能体生成你还没有的词汇。然后深入参加交互式学习课程，你可以：

知道/不知道界面：对每个单词进行简单的二进制选择

渐进式披露：当你不知道单词时显示定义、示例和视觉效果

上下文感知生成：排除你已经知道的单词，专注于你选择的难度等级

视觉集成：为你正在学习的单词生成图像，以创建更强的记忆联系

列表构建：将学过的单词添加到现有列表或创建新的上下文特定集合

不再手动搜索单词——只需选择一个主题和难度，就能获得适应你知识的学习体验。

这是事情变得真正互动的地方。使用 OpenAI 的语音 AI 智能体，你可以与 LLM 导师就你的词汇单词进行实际的口语对话。练习发音，提出问题，并通过自然语音获得即时反馈。这就像有一个语言交换伙伴全天候可用，他精确了解你在学什么单词。语音 AI 智能体可以访问你的列表，帮助你学习你已经拥有的单词，它还可以通过使用工具来添加新单词到你的列表中。

一旦你通过这些方法发现了单词，你可以：

学习：通过 5 种不同的问题类型进行练习（选择题、填空、配对、真假题和句子完成）——所有这些都可在你的设置中配置

测验：测试你的知识并通过已学要点追踪进度

语音练习：与 LLM 语音导师就你的词汇进行对话

轻阅读：生成突出你词汇中的单词的阅读段落

🔍 单词详情页面 - 深入了解每个单词

你的词汇中的每个单词都有自己的综合页面，你可以：

上下文探索器：查看相同单词如何在不同列表中出现不同含义，并在每个上下文中追踪你的进度

示例生成器：创建带有翻译和详细使用说明的上下文示例句子

视觉学习：生成 LLM 图像或查找代表该单词特定上下文的库存照片

相似单词发现：查找同义词和可互换的单词，以及示例和使用说明

智能收集：将发现的相似单词添加到你的现有列表或创建新的上下文特定集合

🔊 音频发音系统 - 每个单词都有声音

沉浸式学习的发音。

该应用现在支持使用任何语言学习任何语言。想用土耳其语学习日语？或者在获得西班牙语解释的同时练习高级英语？只需在设置中配置你的本机语言（基础）和目标语言。LLM 甚至验证特定的语言变体，如"Japanese with Hiragana"或"Brazilian Portuguese"。

通过精选的词汇列表快速启动你的学习。按类别、难度和标签浏览模板，然后克隆它们来创建你自己的自定义列表。

📝 经典词汇列表 - 原始的力量

当然，原始的方式仍然有效！以传统方式创建你自己的上下文感知列表：

创建自定义列表：制作任何名称、描述和上下文的列表（如"哈利波特书"、"商务会议词汇"等）

立即添加单词：只需输入一个单词——它会自动在你选择的上下文中定义

上下文感知定义：每个单词根据你列表的上下文获得其含义，所以"bank"在"金融术语"中的意义与"地理词汇"中不同

手动控制：当你在阅读、看电影或对话中遇到特定单词时完美

灵活的组织：以你想要的方式组织你的词汇

当你确切知道想学什么单词时，这仍然是建立词汇最直接的方式！

关键优势是该应用将你的学习与你最初看到单词的上下文联系在一起。通过在原始设置中回到它们，你强化了那些特定的神经通路，加快了记忆保持，使学习明显更有效。

简而言之，这就像有一个个性化的 Duolingo，你可以从自己的列表中创建和学习，但增加了自然词汇发现和语音交互的功能增强。这是沉浸自己在语言中并取得稳定进展的强大方式。

🎯 推荐的学习流程

选择适合你学习风格和情况的方法：

🚀 发现路径 - 适合想要轻松学习的探险家

当你想扩展词汇而不需要费力寻找单词时完美：

自然发现单词：视觉花园：查看生成的上下文中的图像，描述你所看到的内容，并根据你错过或可以更好地表达的内容获取词汇建议 获取新单词：创建一个包含你感兴趣的任何上下文的会话，然后通过适合你学习水平的 LLM 生成词汇的交互式知道/不知道会话

自然发现单词：

视觉花园：查看生成的上下文中的图像，描述你所看到的内容，并根据你错过或可以更好地表达的内容获取词汇建议

获取新单词：创建一个包含你感兴趣的任何上下文的会话，然后通过适合你学习水平的 LLM 生成词汇的交互式知道/不知道会话

构建你的词汇集合

添加发现的单词到现有列表或创建新的上下文特定列表

使用模板库快速开始使用专业策划的词表

探索与扩展

点击任何单词访问其词汇详情页面进行深度探索

生成例句、找到相似单词并创建视觉关联

添加发现的相似单词来进一步扩展词汇量

练习与强化

使用语音聊天与真实对话讨论你的词汇

生成突出你词汇单词的轻阅读段落

进入学习模式并使用各种题型进行练习

进行测验以评估你的掌握程度并收集学习积分

📚 传统路径 - 适合知道自己想学什么的专注学习者

当你遇到特定单词并想立即学习时很完美：

创建上下文感知列表

制作具有特定上下文的单词列表（哈利波特书籍、商务词汇等）

只需键入你遇到的单词并获得即时的上下文感知定义

深入钻研单词

使用词汇详情页面深入探索每个单词

生成例句、找到相似单词并创建视觉关联

添加发现的相似单词来扩展你的列表

练习与掌握

使用语音聊天练习你的特定词汇

生成使用你收集单词的轻阅读文章

进入学习模式并进行测验以系统地掌握你精选的词汇

随时返回词汇详情页面以复习、找到更多相似单词或生成新的例句

两条路径都能带来相同的综合学习体验——你甚至可以将它们结合起来！关键是 WordPecker 能够适应你偏好的任何学习方式。

✅ 最近实现的功能

多种题型：现在支持 5 种不同的练习类型 - 选择题、填空题、匹配题、判断题和句子完成题（均可在设置中配置）

愿景花园：LLM 驱动的图像描述，用于自然词汇发现

语音聊天：使用 OpenAI 实时 API 与 LLM 辅导员进行实时语音对话

词汇详情页面：深入研究单个单词，包括上下文探索、例句和相似单词

音频发音系统：ElevenLabs 集成，具有发音和缓存功能

多语言支持：使用任何语言学习任何语言，并通过 LLM 验证

模板库：可克隆和自定义的词汇列表

经典词表：传统手动单词输入，具有即时上下文感知定义

轻阅读：突出你的词汇单词的生成阅读段落

进度跟踪：简单的学习积分系统来追踪你的词汇掌握

获取新单词：基于主题和难度级别的 LLM 生成的词汇发现和交互式学习课程

高级进度分析：详细的统计数据、掌握百分比、学习连胜和每日目标

增强的语音功能：更自然的对话流程、发音评分和基于语音的练习

间隔重复：基于遗忘曲线的智能单词复习调度

列表分享：允许用户与他人分享他们的自定义词汇列表

移动应用：原生 iOS 和 Android 应用程序，方便随时学习

浏览器扩展：在阅读网页时直接添加新单词

离线模式：下载列表并在没有互联网连接的情况下练习

游戏化：成就、徽章、排行榜和学习挑战

LLM 辅导员人设：选择具有独特教学风格的不同 LLM 辅导员

社区功能：学习小组、词汇挑战和同伴学习

高级分析：关于你的学习模式的详细见解和优化建议

前提条件

• Node.js（v18 或更高版本）
• MongoDB（本地或云实例）
• Pexels API 密钥（可选 - 用于愿景花园库存照片）
• ElevenLabs API 密钥（可选 - 用于音频发音功能）

安装

克隆仓库：

git clone https://github.com/baturyilmaz/wordpecker-app.git
cd wordpecker-app

安装依赖项：

# 安装后端依赖
cd backend
npm install

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

安装并启动 MongoDB：

# macOS（使用 Homebrew）
brew install mongodb/brew/mongodb-community
brew services start mongodb/brew/mongodb-community

# Ubuntu
sudo apt-get install mongodb
sudo systemctl start mongodb

# Windows
# 从 https://www.mongodb.com/try/download/community 下载并安装

或使用 MongoDB Atlas（云端）：

在 https://www.mongodb.com/atlas 创建免费账户

获取你的连接字符串

环境配置

后端 .env 文件：

PORT=3000
NODE_ENV=development
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
PEXELS_API_KEY=your_pexels_api_key_here  # 可选，用于愿景花园库存照片
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here  # 可选，用于音频功能
MONGODB_URL=mongodb://localhost:27017/wordpecker

前端 .env 文件：

VITE_API_URL=http://localhost:3000

注意：对于 MongoDB Atlas，在 MONGODB_URL 中使用你的连接字符串：

MONGODB_URL=mongodb+srv://username:password@cluster.mongodb.net/wordpecker

数据库将在你首次启动后端时自动创建。无需手动数据库设置，因为 MongoDB 是无模式的，Mongoose 将处理集合创建。

启动应用

后端：

cd backend
npm run dev

前端：

cd frontend
npm run dev

Docker 设置（推荐）

为了获得最简单的设置体验，使用 Docker 运行整个应用程序，包括 MongoDB 和用于开发的热重载：

前置条件

• 系统上安装了 Docker 和 Docker Compose

使用 Docker 快速启动

克隆并导航到项目：

git clone https://github.com/baturyilmaz/wordpecker-app.git
cd wordpecker-app

设置环境变量：

# 复制 Docker 环境模板
cp .env.docker .env

# 编辑 .env 并添加你的 API 密钥
OPENAI_API_KEY=your_actual_openai_api_key_here
PEXELS_API_KEY=your_actual_pexels_api_key_here  # 可选，用于愿景花园库存照片
ELEVENLABS_API_KEY=your_actual_elevenlabs_api_key_here  # 可选，用于音频功能

启动所有服务（MongoDB + 后端 + 前端）：

# 使用热重载启动开发环境
docker-compose up --build

访问应用程序：

• 前端：http://localhost:5173（Vite dev 服务器，支持热重载）
• 后端 API：http://localhost:3000（支持热重载）
• MongoDB：localhost:27017（用户名：admin，密码：password）

Docker Compose 命令

# 使用热重载启动开发环境
docker-compose up --build

# 在后台运行
docker-compose up -d

# 停止所有服务
docker-compose down

# 停止并删除卷（清除数据库）
docker-compose down -v

# 查看日志
docker-compose logs -f

# 查看特定服务的日志
docker-compose logs -f backend
docker-compose logs -f frontend

# 重建特定服务
docker-compose build backend --no-cache

使用 Docker 时，MongoDB 运行时的凭证为：

• 用户名：admin
• 密码：password
• 主机：localhost:27017

你可以使用 MongoDB Compass 或 mongosh 等工具连接到 MongoDB：

# 使用 mongosh
mongosh "mongodb://admin:password@localhost:27017/wordpecker?authSource=admin"

仅运行 MongoDB（使用 Docker）

如果你更喜欢仅在 Docker 中运行 MongoDB，而在本地运行后端/前端：

# 仅启动 MongoDB
docker-compose -f docker-compose.mongo.yml up -d

# 更新你的后端 .env 文件以使用：
MONGODB_URL=mongodb://admin:password@localhost:27017/wordpecker?authSource=admin

然后在本地运行后端和前端

cd backend && npm run dev
cd frontend && npm run dev

为了方便，使用提供的启动脚本：

# 确保已安装 Docker 和 Docker Compose
./scripts/docker-dev.sh

检查 .env 文件是否存在，从模板创建

验证 OpenAI API 密钥是否已设置

清理旧的容器和镜像

在开发模式下启动所有服务

提示添加 ElevenLabs API 密钥用于音频功能（可选）

后端无法连接 MongoDB：

检查 MongoDB 容器是否健康：docker-compose ps

查看日志：docker-compose logs mongodb

后端具有重试逻辑，将尝试连接 5 次

Docker 设置使用端口 5173（前端）、3000（后端）、27017（mongodb）

如需更改端口，编辑 docker-compose.yml

容器构建问题：

不使用缓存重新构建：docker-compose build --no-cache

清理所有内容：docker system prune -a

环境变量：

确保 .env 文件已设置 OPENAI_API_KEY

可选添加 ELEVENLABS_API_KEY 用于音频发音功能

检查环境变量是否已加载：docker-compose config

前端：React.js with TypeScript、Chakra UI 组件、Framer Motion 动画

后端：Express.js with TypeScript、基于 AI 智能体的 LLM 架构

数据库：MongoDB with Mongoose ODM

LLM：OpenAI API（GPT-4、DALL-E、Realtime Voice API）| @openai/agents SDK

音频：ElevenLabs API 用于发音、音频缓存系统

图片：LLM 生成（DALL-E）和库存照片（Pexels 集成）

部署：Docker 支持开发，支持热重载

单用户：不需要身份验证 - 基于 localStorage 的用户标识

欢迎贡献！

创建功能分支