FreeLingo

FreeLingo 是一个开源、可自托管的 AI 语言学习平台。它通过 CEFR 分级测评、结构化学习计划、AI 课程、间隔重复、阅读与听力练习、文字或语音导师，帮助学习者从输入逐步转向主动表达。

本文介绍当前 main 分支，其中既包含上游 FreeLingo 的完整功能，也包含本仓库针对中文母语学习者、科研英语工作流、Codex App Server 和课程加载性能所做的增强。

English README / 英文原文

适合哪些学习目标

• 按 CEFR A1–C2 路线系统学习语言。
• 学习词汇、搭配、短语、语法、阅读、写作、听力和口语。
• 通过 SM-2 间隔重复和主动回忆巩固内容。
• 以英语释义、上下文、完形填空和输出练习为主，减少对逐句翻译的依赖。
• 从论文、文章、书籍等真实材料中挑选值得学习的词语，再进入结构化复习。

当前分支的主要增强

简体中文界面和中文母语支持

• zh 已作为独立的界面语言和母语代码接入注册、个人资料及语言选择流程。
• 课程、练习提示、词汇、语法、短语和导师反馈可以使用学习者的母语提供辅助说明。
• 中文母语与“学习中文”相互独立：界面/母语使用 zh，普通话目标语言使用 zh-CN。
• AI Tutor 默认鼓励英语解释英语、改写、搭配与词块学习，并指出“语法正确但不自然”的表达。

更快的学习计划加载

• Dashboard 和 My Plan 首次读取计划时不再同步等待模型生成课程。
• 缺失课程由显式后台任务生成；Redis 锁确保同一用户、计划和学习日不会并发重复生成。
• 前端先显示现有计划和 generating、cooldown 等状态，再通过安静请求更新课程，不触发全局遮罩层。
• 后台失败会进入短暂冷却，避免浏览器刷新造成连续模型调用。

Codex App Server 接入

• 可选的 codex_app_server LLM provider 通过私有 Unix socket 访问已独立认证的 Codex App Server。
• 普通请求、流式 Tutor 和结构化生成分别使用 AI_MODEL_FAST、AI_MODEL_SMART、AI_MODEL_DEEP。
• 启动时通过 App Server 的 model/list 校验模型 ID，避免凭自然语言名称猜测模型。
• App Server 不提供浏览器可访问的 TCP 端口，也不会把 Codex 主机工具映射给 FreeLingo。
• Unix socket WebSocket 客户端禁用了冲突的应用层 keepalive ping，同时保留完整请求超时。

Codex App Server 是可选集成，不包含在上游基础 Compose 栈中。使用时应由管理员单独部署和认证，并只向 FreeLingo backend 挂载权限受限的 socket。

科研材料学习和 LinguaCafe 导入

• Flashcards → Import 可以导入 LinguaCafe 导出的学习项目。
• 仅接收用户明确标记为学习阶段的单词、短语、搭配、词块、学术表达和科学术语，不会自动导入所有见过的词。
• 导入前提供预览，并生成英语优先的释义、上下文和科学英语学习信息。
• 导入结果进入 FreeLingo 原有的、按学习计划隔离的 SM-2 调度器。
• 导入具有幂等保护；两个应用不共享数据库，也不会让两个 SRS 调度器相互覆盖。

其他本地增强

• 管理员可发布多语言 Dashboard 公告，并通过版本号让已读用户在内容更新后重新看到。
• 邮箱验证、密码重置、多语言静态资源原生说明、语音记录所属计划校验等流程得到加强。
• 版本 1.9.1 的完整测试基线为后端 1049 项、85.00% 覆盖率；前端 50 个文件、487 项测试。

上游核心功能

测评和学习计划

• 确定性的初始分级测评和 CEFR 等级判断。
• 4、8、12 或 16 周学习强度。
• 按单元、能力目标和前置条件组织的周计划。
• 语法、词汇、阅读、写作、复习等课程依次解锁。
• 等级结业测试、XP、连续学习天数、技能分数和能力进度。

课程和复习

• 在课程体系约束内由 LLM 生成个性化课程和练习。
• Flashcard 使用 SM-2 间隔重复。
• 支持选择题、填空、自由写作和发音练习。
• 已完成课程可只读复习，不会重复奖励进度。
• 课程完成、进度和能力更新采用原子事务，重试不会重复记分。

AI Tutor 与记忆

• AI 导师名为 Lingu，支持流式文字对话和实时语音对话。
• 导师可以在一次受控工具调用中保存对学习有帮助的长期记忆。
• 所有已登录用户都可以在设置中添加、查看、删除或清空自己的记忆。
• 记忆属于用户全局数据；删除某个学习语言不会删除这些记忆。

听力、阅读和语音

• 听力练习由 LLM 生成内容，通过 TTS 合成音频并按等级缓存。
• 阅读练习提供文章和理解题，按正确答案累计 XP。
• 阅读题和听力题中的正文单词可进入 Flashcard 查词流程。
• 发音和语音对话可使用本地 Kokoro/faster-whisper，或 OpenAI TTS/Whisper API。
• 实时对话支持 VAD、打断、连续音频和文字转录保存。

多语言、多用户和管理

• 一个用户可同时学习多种语言；每种目标语言有独立计划、进度、卡片、对话和能力数据。
• 支持 en-GB、en-US、es-ES、it-IT、pt-PT、de-DE、fr-FR、ja-JP、ko-KR、zh-CN。
• 支持管理员/普通用户、邀请链接、关闭公开注册、配额和维护模式。
• 可选 Stripe 订阅、反馈与投票、用户评价、公告和管理后台。
• 自托管模式不受 hosted freemium 配额限制。

技术架构

• 前端：Next.js 16 App Router、React、Tailwind CSS、shadcn/ui、Zustand、next-intl。
• 后端：Python 3.14、FastAPI、SQLAlchemy async、Alembic、Pydantic v2。
• 数据库：PostgreSQL 16。
• 缓存和任务锁：Redis 7。
• LLM：Ollama、OpenAI、Anthropic、DeepSeek 或 Codex App Server。
• TTS：Kokoro-FastAPI 或 OpenAI TTS。
• STT：faster-whisper 或 OpenAI Whisper。
• 部署：Docker Compose。

浏览器只访问 Web origin。LLM、TTS、STT、数据库和 Redis 都由 backend 或 Docker 内部网络访问，前端不应直接连接这些内部服务。

目录结构

freelingo/
├── assets/               # Logo 和静态资源
├── backend/              # FastAPI 后端
├── frontend/             # Next.js 前端
├── messages/             # 界面翻译，包括 zh
├── specs/                # 当前实现规范
├── docker-compose.yml    # 基础生产 Compose
├── .env.example          # 环境变量模板
├── CHANGELOG.md          # 版本历史
├── README.md             # 中文说明
└── README_EN.md          # 上游英文说明

Docker 快速开始

要求：Docker、Docker Compose 和 Git。LLM 可使用宿主机 Ollama，也可以配置其他 provider。

git clone ssh://git@tmytimidly.com:222/CounterAttack/Freelingo.git
cd Freelingo
cp .env.example .env

编辑 .env，至少检查数据库密码、SECRET_KEY、LLM provider 和模型配置，然后启动：

docker compose up -d

数据库迁移会在 backend 启动时自动执行。默认访问地址为：

http://localhost:3000
http://<Linux-LAN-IP>:3000

当 FIRST_USER_IS_ADMIN=true 时，第一个注册用户会自动成为管理员。

构建当前分支源码

基础 Compose 默认引用发布镜像。若要运行本仓库 main 中的修改，应使用一个本地 override，例如：

services:
  backend:
    image: freelingo-backend:local
    pull_policy: never
    build:
      context: ./backend
      dockerfile: Dockerfile

  frontend:
    image: freelingo-frontend:local
    pull_policy: never
    build:
      context: .
      dockerfile: frontend/Dockerfile

保存为 docker-compose.local.yml 后执行：

docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build

关键配置

LLM

• LLM_PROVIDER=ollama：使用本地 Ollama。
• LLM_PROVIDER=openai：使用 OpenAI API。
• LLM_PROVIDER=anthropic：使用 Anthropic API。
• LLM_PROVIDER=deepseek：使用 DeepSeek API。
• LLM_PROVIDER=codex_app_server：使用私有 Unix socket 上的 Codex App Server。

不要把 API key、token、密码或 socket 凭据写入源码；只放入未提交的 .env 或部署侧 secret。

TTS 和 STT

TTS_PROVIDER=local
STT_PROVIDER=local

本地模式分别使用 Kokoro 和 faster-whisper，建议使用 NVIDIA GPU。也可以分别切换到 openai。Kokoro-82M 主要提供英语声音；学习非英语目标语言时应确认所选 TTS provider 支持该语言。

Redis 宿主机设置

Redis 进行后台保存时建议 Linux 宿主机启用：

sudo sysctl vm.overcommit_memory=1

是否持久写入系统配置应由服务器管理员自行决定。

LAN、WebSocket 与安全

• 普通页面可通过 http://<Linux-LAN-IP>:3000 在局域网访问。
• 实时语音使用 /ws/conversation，生产反向代理必须正确转发 WebSocket upgrade。
• 浏览器麦克风通常要求安全上下文，即 HTTPS 或 localhost；普通 LAN HTTP 可以学习，但不保证 Chrome 开放麦克风。
• 不要向 LAN 或公网发布 PostgreSQL、Redis、backend 内部端口或 Codex socket。
• 如果服务将来通过路由器暴露到公网，应配置 HTTPS、可靠认证和最小防火墙规则。

数据持久化和升级

• PostgreSQL、Redis、头像、音频和 TTS 预览使用 Compose volume 或 DATA_PATH 下的挂载目录。
• docker compose down 不会删除 volume；不要使用 docker compose down -v，除非明确准备永久删除数据。
• 升级前应备份数据库、上传内容、音频和 .env。
• 本分支包含本地修改，升级时不要直接覆盖：先 git fetch --all --tags，评估新稳定版本的迁移和 Compose 变化，再 rebase 或 cherry-pick。

开发和验证

后端：

cd backend
pytest -v

前端：

cd frontend
npm run lint
npx tsc --noEmit
npm run test:run

更详细的架构和 API 说明位于 specs/，开发环境说明见 DEVELOPMENT.md。

上游、贡献和许可

• 上游项目：ArtCC/freelingo
• 上游作者：Arturo Carretero Calvo（@artcc）
• 贡献要求见 CONTRIBUTING.md 和 CONTRIBUTOR_LICENSE_AGREEMENT.md。
• 本项目依据 GNU Affero General Public License v3 发布；商业许可说明见 COMMERCIAL_LICENSE.md。