Good Good Study 是一个本地视频英语学习系统，支持影子跟读、单词加强学习、情境阅读单词等功能。
- 系统文件框选择本地视频，并由后端自动扫描同目录字幕（亦可路径/上传）
- HTTP Range 视频播放、字幕时间轴、逐句定位、刷新恢复和点击查词
- 英文分词、基础词形归一、单词与字幕句/视频绑定
- Free Dictionary API 免费英文词典
- Azure Translator、DeepL API Free、LibreTranslate 可替换翻译接口；未配置时可回退模型中心的翻译模型
- 将中文字幕持久绑定到英文字幕句，并在播放器显示双语字幕
- 每日选词计划、锁定版本和学习事件
- 本地选择题，以及通过AI重新出题
- 根据今日词汇生成恰好三篇不同情境的双语阅读和阅读理解题
- GitHub式学习热力图、测试正确率、具体学习单词与每日学习记录
- 可配置模型中心：OpenAI、NVIDIA NIM及任意OpenAI兼容接口，支持无密钥本地服务
- 全局默认模型，以及词汇释义、翻译、选择题、情境阅读模块级覆盖
- Windows与手机浏览器响应式PWA界面
默认使用规则见 docs/handbook/，包括各页功能、今日计划配比、词典来源 与 情境阅读主题。页面 UI 只保留必要操作，细则放在手册中。
- React 19、TypeScript、Vite、PWA、TanStack Query
- Fastify、tRPC、Zod
- SQLite、Drizzle ORM
- OpenAI SDK及OpenAI兼容接口
- pnpm Monorepo
需要 Node.js 22+ 和 pnpm 10+。
cd GoodGoodStudy
.\scripts\setup.ps1
pnpm dev默认地址：
- Web：
http://localhost:5173 - API：
http://localhost:4310 - 健康检查：
http://localhost:4310/health
初始化脚本会：
- 创建
.env，并自动生成用于本地 API Key 加密的随机密钥 - 安装依赖并执行数据库迁移
- 检查 / 自动准备 FFmpeg（用于不兼容音轨转换与封面抽取）
start.ps1 会在启动前自动执行尚未应用的数据库迁移，并尽量确保 FFmpeg 可用。
部分视频的音轨（如 AC-3 / DTS）浏览器无法直接播放；导入时还会抽取约第 10 秒画面作为封面。这些能力依赖 FFmpeg + FFprobe。
解析顺序：
FFMPEG_PATH / FFPROBE_PATH
→ tools/ffmpeg 托管安装
→ 系统 PATH
→ 自动下载官方静态构建到 tools/ffmpeg
首次运行 setup.ps1、start.ps1 或导入需要转码的视频时，会自动检查；若本机没有，会下载到 tools/ffmpeg（已 gitignore）。也可手动：
pnpm ffmpeg:ensure # 检查并按需下载
pnpm ffmpeg:check # 仅检查是否可用Windows / Linux / macOS 均支持自动准备；失败时请按终端提示手动安装，并在 .env 中设置路径。详见 配置说明。
打开“模型中心”后可以：
- 添加 OpenAI、NVIDIA NIM 或自定义兼容Provider。
- 设置 Base URL、API风格和API Key。
- 从Provider的
/models同步模型，或手工添加模型ID。 - 选择全局默认模型。
- 为语境查词、词汇测试、多情境阅读和翻译分别覆盖模型。
解析顺序为：
模块指定模型 → 全局默认模型 → 显式提示未配置
OpenAI默认使用Responses API与Structured Outputs；NVIDIA和其他兼容服务默认使用Chat Completions。兼容服务返回的JSON还会经过Zod和业务规则二次校验。
Chat Completions Provider 可以选择三种兼容模式：JSON Schema、JSON Object、仅提示词约束。Ollama、LM Studio、vLLM等本地接口可以关闭“需要 API Key”。自定义 Headers 会整体加密保存且不会返回浏览器。
API Key只发送到本地后端，以AES-256-GCM加密后保存在SQLite中；读取配置时前端只能得到 hasApiKey，无法取回密钥。自定义 Headers 使用同样的加密策略。
免费英文释义无需密钥。中文翻译可以在 .env 中配置：
TRANSLATION_PROVIDER=auto
AZURE_TRANSLATOR_KEY=
AZURE_TRANSLATOR_REGION=
DEEPL_API_KEY=
LIBRETRANSLATE_URL=
LIBRETRANSLATE_API_KEY=auto 会依次选择已经配置的 Azure Translator、DeepL 或 LibreTranslate。翻译结果缓存在本地数据库中。
如果三者均未配置，系统会尝试使用模型中心里“翻译”模块的模型；未配置任何模型时会给出明确提示。
默认只监听Windows本机。需要在同一可信局域网使用手机时：
- 将
.env中HOST改为0.0.0.0。 - 把
WEB_ORIGIN和VITE_API_URL改为Windows电脑的局域网地址。 - 使用
pnpm --filter @context-english/web dev --host 0.0.0.0启动Web端。 - 在手机浏览器打开
http://电脑IP:5173，然后添加到主屏幕。
当前版本是单用户模式，不包含局域网认证。只应在可信家庭网络使用，不能直接把端口暴露到公网。
pnpm dev # 同时启动 Web 与 API
pnpm typecheck # 全工作区类型检查
pnpm test # 全工作区测试
pnpm build # 生产构建
pnpm db:migrate # 执行数据库迁移
pnpm db:generate # 根据 Drizzle Schema 生成迁移
pnpm ffmpeg:ensure # 检查并自动下载 / 配置 FFmpeg
pnpm ffmpeg:check # 仅检查 FFmpeg 是否可用（不下载）- 数据库默认位于
data/context-english.db。 - 视频缓存 / 兼容转码文件默认位于
data/media/（主流程默认只引用源路径，不复制整片）。 - 托管的 FFmpeg 二进制默认位于
tools/ffmpeg/（可自动下载，勿提交到 Git）。 data/、.env、tools/ffmpeg/已加入.gitignore。- 字幕、视频和学习记录不会自动上传外部服务。
- 只有显式触发 AI 或翻译操作时，相应文本才会发送给所配置的 Provider。
- 默认是单用户、本地运行，不包含账号与云同步。
- 手机访问依赖 Windows 主机在线，并需要自行配置局域网访问与安全策略。
- 视频优先支持浏览器原生可播放的 MP4/WebM；若音轨为 AC-3/DTS 等不兼容格式，会自动仅转音频为 AAC（视频 copy）并缓存兼容文件。
- 音轨转换与封面抽取依赖 FFmpeg；未安装时会自动下载到
tools/ffmpeg，也可手动设置FFMPEG_PATH/FFPROBE_PATH。 - MKV、HEVC 等复杂视频编码可能仍需后续接入完整转码。
- 没有配置模型时，本地选择题仍可使用；AI 释义和三篇情境阅读会明确提示先配置模型。
本项目仅供学习与交流使用，禁止用于任何商业或盈利目的。
允许：
- 个人学习、阅读源码
- 非商业的研究、教学演示
- 在注明来源的前提下分享
禁止：
- 售卖本项目或其修改版
- 用于商业产品、商业服务或收费项目
- 以本项目进行任何形式的盈利
如需商业使用，请先联系作者获得授权。