LangFlow — YouTube Language Learner

LangFlow 是一个 Chrome MV3 扩展，用来在 YouTube 上做语言学习：显示双语字幕、点词保存、悬停查词，并用 SM-2 间隔重复复习单词。

功能

• YouTube 字幕叠层：英文字幕 + 自动翻译。
• 单词交互：左键打开词典卡片，右键直接保存到词库。
• 悬停查词：显示释义，支持发音。
• 自动暂停循环：按字幕片段暂停、回放，适合精听。
• SRS 复习：按 SM-2 算法安排复习。
• 侧边栏：词典、字幕记录、词库、复习四个视图。
• 导出：JSON 和 Anki TSV。
• 可选同步：把未同步单词推送到自定义 API。

安装

1. 打开 Chrome/Edge 的扩展管理页：chrome://extensions/。
2. 开启「开发者模式」。
3. 点击「加载已解压的扩展程序」。
4. 选择本项目里的 extension/ 文件夹。
5. 打开带字幕的 YouTube 视频开始使用。

这个项目没有构建步骤，extension/ 就是可加载的扩展目录。

项目结构

extension/manifest.json                  Chrome 扩展清单
extension/background/service-worker.js   后台消息中心、IndexedDB 唯一入口、徽标、同步
extension/content/content.js             content script 入口、YouTube SPA 重新初始化
extension/content/youtube-page-script.js YouTube main world 脚本，读取播放器和字幕 DOM
extension/content/subtitle-overlay.js    双语字幕叠层、自动暂停、SRS 单词颜色
extension/content/word-click.js          点击单词查词和保存
extension/content/hover-tooltip.js       悬停释义和发音
extension/db/indexeddb.js                LangFlowDB 数据层
extension/ui/flashcard-ui.js             popup/sidepanel 共用复习卡片
extension/ui/vocab-list-ui.js            popup/sidepanel 共用词库列表
extension/sidepanel/                     侧边栏界面
extension/popup/                         扩展弹窗
extension/options/                       设置页
extension/utils/                         翻译、词形还原、SRS、TTS、通用工具

维护规则

项目规则在 AGENTS.md 和 CLAUDE.md 中保持一致。改功能前先看规则，尤其是这些边界：

• IndexedDB 只能在 extension/background/service-worker.js 通过 LangFlowDB 使用。
• content、popup、sidepanel 之间只通过 chrome.runtime.sendMessage 和后台通信。
• extension/background/service-worker.js 的 importScripts() 路径以 background/ 为基准。
• extension/content/youtube-page-script.js 和 content script 之间只用 window.postMessage，source 固定为 langflow-page / langflow-content。
• YouTube 字幕采集依赖 .ytp-caption-window-container 和 .ytp-caption-segment。字幕失效时优先查 extractCaptionText()。
• MV3 service worker 会随时休眠，消息处理里必须懒加载 initDB()。

数据与同步

本地单词数据存储在浏览器 IndexedDB：langflow_db。复习、词库、导出都读取本地数据。

翻译使用 translate.googleapis.com 的非官方接口，结果只做会话内缓存。同步功能会把未同步单词发送到设置页配置的 API /batch 接口。

验证

当前项目没有自动化测试。提交前至少做这些轻量检查：

Get-Content -LiteralPath extension/manifest.json -Raw | ConvertFrom-Json | Out-Null
git diff --check

改字幕、播放器或快捷键时，还需要手动加载扩展，在 YouTube 带字幕视频上验证。