IELTS SLAYER

无 AI · 纯键盘 · 原声强刺激 — 把雅思听力 / 口语 / 词汇训练压成一套可盲操的本地工具。

放弃昂贵且可能幻觉的 AI 批改，用 影视原声切片 + FSRS 间隔重复 + 双轨波形跟读，把自学效率拉到极致。

---

为什么是「无 AI」

传统 AI 工具	IELTS SLAYER
等大模型几秒才出结果	跳转 / 录音 / 打分目标 < 50ms 盲操响应
发音打分常不准、不可复现	原声 vs 自己 双轨交替 + 波形对比，耳朵自判
Token 费用与隐私顾虑	本地优先：媒体与进度在你自己的机器上
抽象释义背词	名场面 ±切片原声 进 FSRS，复习即听真语境

核心理念详见 docs/plan.md。

---

功能一览

模块	做什么	入口
指挥中心	健康探活、待复习队列、媒体就绪、粘贴 YouTube 一键导入	首页
媒体库 Vault	已导入视频列表，进播放器或跟读室	Vault
沉浸播放器	字幕时间轴高亮、点句跳转、划词斩入 FSRS	Player
斩词台 Slash	FSRS 待复习；Space 揭晓 / 播切片；1–4 评分	Slash
影子跟读 Shadow	句级 A-B 循环、按住 Space 录音、WaveSurfer 双轨、Tab 交替对比	Shadow

指挥中心

待复习队列、影子跟读入口、YouTube 一键导入与系统就绪概览。

沉浸播放器

字幕时间轴高亮、点句跳转；划词看释义，Enter 切片入库。

斩词台

名场面音频切片 + FSRS；Space 重播，1–4 盲操评分。

影子跟读

句级 A-B、双波形对比；Tab 交替听原声与自己，耳朵自判。

媒体库

YouTube / 本地素材统一索引，一键进播放或跟读。

---

技术栈

YouTube / 本地媒体 ──► yt-dlp + FFmpeg ──► go-astisub ──► PostgreSQL
                                                              │
React (Vite) + WaveSurfer ◄── GoFrame API ◄── Redis           │
     │                              │                         │
  斩词 / 跟读 UI              go-fsrs 调度 ◄──────────────────┘

层	选型
前端	React 19 · Vite · Tailwind 4 · shadcn/ui · TanStack Query · Wavesurfer.js · i18n（中/英）
后端	GoFrame · go-astisub · go-fsrs
数据	PostgreSQL 16 · Redis 7
媒体	yt-dlp（拉流+英文字幕）· FFmpeg（句/词音频切片）· Deno/Node（新版 YouTube JS runtime）
词库	ECDICT（ielts tag）· 发音回落 有道 CDN

设计系统（深色 / 琥珀主色 / Geist Mono / 键盘优先）：docs/design-system.md。

---

快速开始

环境要求

依赖	说明
Go 1.25+	后端
Node.js 20+（建议）+ npm/pnpm	前端
Docker	仅用于 Postgres + Redis
yt-dlp · FFmpeg	视频导入与切片；缺失时相关 API fail-closed 明确报错
Deno 或 Node	新版 yt-dlp 提取 YouTube 时常需要

1. 基础设施

cd backend
docker compose up -d
# Postgres → localhost:5433 · Redis → localhost:6380
# 首次启动会自动执行 manifest/sql/*.sql（挂载到 initdb）

2. 后端配置

# 若尚无 config.yaml，从示例复制（勿把本机绝对路径提交进仓库）
cp manifest/config/config.example.yaml manifest/config/config.yaml
# 按需改 database / redis / media.ytdlpPath / media.ffmpegPath / media.jsRuntimes

go mod tidy
go run .          # HTTP :8011 · Swagger http://localhost:8011/swagger

3. 前端

cd web
npm install
npm run dev       # http://127.0.0.1:5188 · /api 与 /media 已代理到 :8011

4.（可选）导入雅思词库

1. 从 skywind3000/ECDICT 下载 ecdict.csv
2. 放到 backend/data/ecdict.csv
3. 执行：

cd backend
# 导入全部 ielts 词条，并默认入队斩词（-enroll=false 可只写词库）
go run . import-ecdict -f ./data/ecdict.csv -tag ielts

5.（可选）导入第一条媒体

# YouTube（需 yt-dlp + JS runtime）
go run . import-video -u "https://www.youtube.com/watch?v=..."

# 或本地音视频 + 英文字幕
go run . import-video -media ./testdata/sample.m4a -sub ./testdata/sample.en.srt -title "Sample"

指挥中心也可直接粘贴 YouTube URL 走 POST /api/v1/videos/import。

---

键盘盲操速查

斩词台 Slash

键	行为
Space	揭晓 / 播放原声切片（无切片则有道发音）
1 / 2 / 3 / 4	FSRS：Again / Hard / Good / Easy

影子跟读 Shadow

键	行为
Space 短按	播放 / 暂停原声
Space 按住	录音（松开结束）
Tab	原声 → 录音 串播对比
L	A-B 循环开关
R	清除录音重录
W	标「需重练」并下一句
Q	跳到下一弱句
↑ ↓	换句
Enter	标掌握并下一句
Esc	退出

完整说明：docs/shadow.md。

---

仓库结构

ielts-project/
├── backend/                 # GoFrame API · Worker/CLI · Docker Compose
│   ├── api/                 # 接口定义
│   ├── internal/            # controller / logic / dao
│   ├── manifest/
│   │   ├── config/          # config.example.yaml · config.yaml（本地）
│   │   └── sql/             # 初始化与迁移
│   ├── utility/             # ytdlp · ffmpeg · subtitle · audio
│   └── doc.md               # 后端事实文档（启动 / API / 联调）
├── web/                     # React 前端
│   └── src/pages/           # CommandCenter · Vault · Player · Slash · Shadow
├── docs/                    # 产品与模块事实文档
│   ├── plan.md              # 哲学与分阶段计划
│   ├── video.md · word.md · shadow.md
│   ├── design-system.md
│   └── screenshots/         # README 用截图（待你提供）
└── design/                  # 设计源图

---

API 速览

Method	Path	说明
GET	/api/v1/health	DB / Redis 探活
GET	/api/v1/words · /words/{id} · /words/stats	词库
GET	/api/v1/slash/due	待复习斩词卡
POST	/api/v1/slash/rate	FSRS 评分 { cardId, rating: 1–4 }
GET	/api/v1/videos · /videos/{id} · /videos/{id}/subtitles	媒体与字幕
POST	/api/v1/videos/import	YouTube URL 或本地 media+sub
POST	/api/v1/videos/slice	划词 → FFmpeg 切片 + FSRS 卡
POST	/api/v1/videos/cue-clip	跟读句级音频（可缓存）
GET	/media/...	静态媒体（data/videos · data/clips）

更全：backend/doc.md · 运行时 OpenAPI：http://localhost:8011/api.json。

---

文档索引

文档	内容
docs/plan.md	无 AI 哲学、闭环、Phase 1–4
docs/video.md	YouTube/本地导入、切片钳制、状态机
docs/word.md	ECDICT + 有道发音方案
docs/shadow.md	跟读闭环与快捷键
docs/design-system.md	GEEKOS 色板与组件约定
backend/doc.md	启动、依赖、API、联调

免责声明

• 本项目面向个人学习与自托管，不提供任何考试成绩保证。
• 通过 yt-dlp 获取的内容须遵守来源平台服务条款与当地版权法；请勿将受版权保护的媒体再分发。
• 跟读辅助指标（时长差、包络相似度）仅为本地启发式参考，不以 AI 打分为准。

---

贡献

Issue / PR 欢迎。改动请尽量对齐现有事实文档（docs/*、backend/doc.md），并保持「键盘优先、无 AI 主路径」的产品边界。

---

许可证

MIT — 免费、可商用、可修改、可再分发；保留版权与许可声明即可。