小语境 · Little Context

一个以固定小故事驱动的英语口语练习工具。学习者扮演故事角色，在六个预设对话点用英语回答；可以查看答案、听示范、重试或跳过。回答只影响练习反馈，不会改变故事大纲、事件顺序和结局。

本项目公开源代码供个人学习、研究和非商业用途使用，禁止商业使用。详见 PolyForm Noncommercial License 1.0.0。

功能

• 三个固定短故事，每个包含 3 个章节和 6 个对话点。
• GPT-Live 实时语音、设备系统音色和文字体验三种练习方式。
• 接入自定义 OpenAI Chat Completions 兼容接口，生成新的固定故事。
• 无 API 时可复制故事提示并转到 ChatGPT 语音练习。
• 点击练习中的英文单词或拖选短语，直接保存为记忆卡片。
• 词根词缀词典：40 个精选构词、132 个 A2–B2 高频词、中英文搜索、构词拆解、词族树、系统朗读和一键制卡。
• 8 周高频词汇计划：每天约 12 分钟，包含构词讲解、词族辨认、拼词、语境选词、口语输出和间隔复习。
• 查看参考答案、中文释义、示范朗读、逐点修正与重试。
• 本设备学习记录、表达复习、Anki 导出、备份、恢复和删除。
• 故事、会话与模型输出使用 Zod 契约校验，服务端控制故事推进。

界面

故事口语练习

单词与短语记忆卡片

词根词缀与词族

词库为本项目独立整理的口语学习精选数据，当前包含 24 个高产词根、16 个常用词缀和 132 个高频词。构词拆解用于辅助记忆，完整词义以单词卡为准；项目只参考 Morpheme Lexicon 的公开功能说明，没有复制其数据库、文案或视觉资产。

8 周学习计划

每周 5 天、每天约 12 分钟。复习项目优先，新内容每天最多 2 个构词和 8 个单词；系统根据独立答对、看答案完成和答错情况安排当天、1、3、7、14 或 30 天后的复习。移动端计划界面见 artifacts/morpheme-plan-mobile.png。

移动端

本地部署

1. 环境要求

• Node.js 24
• npm 10 或更高版本
• 推荐使用最新版 Chrome 或 Edge，以获得较完整的浏览器语音识别支持

2. 下载和启动

git clone https://github.com/sudubin/little-context.git
cd little-context
npm install
cp .env.example .env
npm run dev

浏览器打开 http://localhost:5173 或 http://127.0.0.1:5173。本地开发会同时接受这两个回环地址。使用其他地址时，请确保 .env 中的 APP_ORIGIN 与浏览器地址完全一致；如需允许多个可信地址，可用逗号分隔配置 APP_ORIGINS。

不填写任何 API Key 也可以使用：

• 本机音色：设备自带的英语音色朗读旁白和角色台词；浏览器支持时可使用麦克风转写回答。
• 文字体验：输入英文回答，体验完整故事、纠正、记录和记忆卡片流程。
• 外部 ChatGPT：复制固定故事提示，在 ChatGPT 网页或客户端中手动开启语音。

3. 启用 GPT-Live

编辑 .env：

OPENAI_API_KEY=你的_OpenAI_API_Key
ACCESS_CODE=自定义私人访问码
COOKIE_SECRET=至少32位的随机字符串
APP_ORIGIN=http://localhost:5173
# 可选：允许多个可信网页来源
APP_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

然后重新运行 npm run dev。OPENAI_API_KEY 只能放在服务端 .env 中，不要写入任何 VITE_ 变量或提交到 GitHub。ChatGPT 会员额度与 OpenAI API 用量相互独立。

其他可选配置参见 .env.example：模型名称、单课时长、请求限制、每日服务额度和 PostgreSQL 地址都可以单独调整。

4. 使用自定义模型生成故事

在首页点击“创作新故事”，填写：

• 公开 HTTPS API 地址，例如 https://api.openai.com/v1
• OpenAI Chat Completions 兼容模型名称
• 临时 API Key
• 故事主题、角色和难度

API Key 会经过本地 Fastify 服务转发，请求结束后从表单清除，不写入 IndexedDB、备份或应用日志。服务端会拒绝 HTTP、本机、私网和链路本地模型地址。

Docker 部署

本机单容器体验

docker build -t little-context .
docker run --rm \
  --env-file .env \
  -e HOST=0.0.0.0 \
  -e PORT=3001 \
  -e APP_ORIGIN=http://localhost:3001 \
  -p 3001:3001 \
  little-context

打开 http://localhost:3001。不设置 DATABASE_URL 时仍可个人体验，学习数据保存在浏览器 IndexedDB。

带 HTTPS 和 PostgreSQL 的部署

在 .env 中设置：

POSTGRES_PASSWORD=使用强密码
APP_DOMAIN=你的域名
APP_ORIGIN=https://你的域名
COOKIE_SECRET=至少32位的随机字符串

将域名解析到服务器后运行：

docker compose up -d --build

Compose 会启动应用、PostgreSQL 和 Caddy。应用启动时自动创建必要的数据表；Caddy 负责 HTTPS 和 WebSocket 反向代理。

常用命令

npm run dev         # 同时启动前端和后端开发服务
npm run typecheck   # TypeScript 类型检查
npm test            # 单元与接口测试
npm run test:e2e    # Playwright 浏览器流程测试
npm run build       # 生产构建
npm start           # 启动构建后的单体服务

PostgreSQL 集成测试需要设置 TEST_DATABASE_URL。自动验证结果与仍需真人检查的项目见 验证记录。

数据与隐私

• 学习记录、自创故事、记忆卡片和词根词缀计划进度默认保存在当前浏览器 IndexedDB。
• 应用不持久保存原始录音。
• GPT-Live 音频会发送给配置的 OpenAI 服务处理。
• 本机音色朗读不发送给模型服务；浏览器语音识别是否联网由浏览器实现决定。
• 自定义模型 API Key 不写入本地数据库、备份或日志。
• 清除浏览器数据前，可在“练习记录”页面导出备份。

技术栈

React、TypeScript、Vite、Fastify、XState、Dexie、Zod、PostgreSQL、Drizzle、WebRTC、Web Speech API、Vitest 和 Playwright。

产品需求和行为规格位于 故事练习 OpenSpec change 与 词根词缀 OpenSpec change。

许可证

本项目采用 PolyForm Noncommercial License 1.0.0。允许个人学习、研究、实验、业余项目及符合许可定义的非商业组织使用、修改和分发；不授予商业用途许可。

本许可证属于 source-available 非商业许可证，并非 OSI 定义的开源许可证。如需商业授权，请联系仓库所有者。