# IELTS SLAYER

**Repository Path**: lin_30_0/ielts-slayer

## Basic Information

- **Project Name**: IELTS SLAYER
- **Description**: 无 AI 雅思邪修：影视原声切片 + FSRS 斩词 + 双轨跟读，纯键盘盲操。GoFrame + React。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Go语言, youtube, React, ielts

## README

# IELTS SLAYER

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

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

[![Go](https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go&logoColor=white)](./backend)
[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black)](./web)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-4169E1?logo=postgresql&logoColor=white)](./backend/docker-compose.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

---

## 为什么是「无 AI」

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

核心理念详见 [`docs/plan.md`](./docs/plan.md)。

---

## 功能一览

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

### 指挥中心

![指挥中心](./docs/screenshots/01-command-center.png)

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

### 沉浸播放器

![沉浸播放器](./docs/screenshots/02-player.png)

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

### 斩词台

![斩词台](./docs/screenshots/03-slash.png)

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

### 影子跟读

![影子跟读](./docs/screenshots/04-shadow.png)

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

### 媒体库

![媒体库](./docs/screenshots/05-vault.png)

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](https://goframe.org) · `go-astisub` · `go-fsrs` |
| 数据 | PostgreSQL 16 · Redis 7 |
| 媒体 | **yt-dlp**（拉流+英文字幕）· **FFmpeg**（句/词音频切片）· Deno/Node（新版 YouTube JS runtime） |
| 词库 | [ECDICT](https://github.com/skywind3000/ECDICT)（`ielts` tag）· 发音回落 [有道 CDN](https://dict.youdao.com/dictvoice) |

设计系统（深色 / 琥珀主色 / Geist Mono / 键盘优先）：[`docs/design-system.md`](./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. 基础设施

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

### 2. 后端配置

```bash
# 若尚无 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. 前端

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

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

1. 从 [skywind3000/ECDICT](https://github.com/skywind3000/ECDICT) 下载 `ecdict.csv`
2. 放到 `backend/data/ecdict.csv`
3. 执行：

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

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

```bash
# 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`](./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`](./backend/doc.md) · 运行时 OpenAPI：`http://localhost:8011/api.json`。

---

## 文档索引

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


## 免责声明

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

---

## 贡献

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

---

## 许可证

[MIT](./LICENSE) — 免费、可商用、可修改、可再分发；保留版权与许可声明即可。