# english_learn

**Repository Path**: simonyuan2019/english_learn

## Basic Information

- **Project Name**: english_learn
- **Description**: english learn, record and export
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-06-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

> 🇬🇧 English version: [README.md](./README.md)

# 📚 英语学习助手 (English Learning Assistant)

> 一款基于浏览器、面向小学生的智能英语学习助手。接入任意 OpenAI 兼容的大模型 API，提供原生语音朗读、学习历史记录、以及一键导出 Markdown / HTML 笔记等功能。

**当前版本：** `v4.0`

---

## ✨ 项目简介

**英语学习助手** 是一个单文件、零依赖的网页应用，旨在让小学生的英语词汇学习变得轻松、高效、可自主掌控。只需输入任意单词、短语，甚至中文词条，应用就会调用大模型生成一份结构化的学习卡片 —— 包含英美音标、词性、中英文释义、用法说明、例句、同义词、反义词和记忆技巧。

所有功能**完全在浏览器中运行**。无需后端、无需数据库、无需构建步骤 —— 打开 HTML 文件即可开始学习。所有数据（API 配置、学习历史、当前会话）均保存在浏览器 `localStorage` 中，每日笔记可一键导出为独立的 `.md` / `.html` 文件，并以 **UTC+8（北京时间）** 时间戳命名。

---

## 🎯 核心功能

| 分类 | 功能 |
|------|------|
| 🤖 **大模型驱动学习** | 兼容任意 OpenAI 格式 API（OpenAI、Ollama、硅基流动、自定义）。每次查询返回结构化 JSON 学习卡片。 |
| 🔊 **语音朗读** | 浏览器原生 `SpeechSynthesis` 发音。可调语速、可选英文音色、一键"🐢 慢速"模式，适合初学者。 |
| 📝 **学习历史** | 自动保存最近 50 条记录。点击任意条目即可瞬间载入复习。 |
| 💾 **每日导出** | 一键导出**今天**的学习内容，同时生成 **Markdown** 和**独立样式 HTML** 文件。文件名采用 `UTC+8` 时间戳。 |
| 🌐 **会话自动保存** | 输入内容和上次结果会在刷新后自动恢复 —— 学习进度永不丢失。 |
| 📱 **响应式设计** | 纯 CSS 打造的精美动画界面，支持移动端自适应。 |

---

## 📂 项目结构

```
English/
├── english_learning.html   # 🚀 主应用（单文件，浏览器直接打开）
├── README.md                # 📖 英文文档
└── README.zh-CN.md          # 📖 中文文档（本文件）
```

> 整个应用就是一个 HTML 文件 —— 无需安装、无需构建、零依赖。

---

## 🚀 快速开始

### 1. 获取 API Key
应用支持任意 **OpenAI 兼容** 的 chat-completions 接口。内置预设：

| 预设 | 接口地址 | 默认模型 |
|------|----------|----------|
| 🤖 OpenAI | `https://api.openai.com/v1` | `gpt-3.5-turbo` |
| 🏠 Ollama（本地） | `http://localhost:11434/v1` | `llama2` |
| 🇨🇳 硅基流动 | `https://api.siliconflow.cn/v1` | `Pro/deepseek-ai/DeepSeek-V3` |
| ⚡ 自定义 | *你的地址* | *你的模型* |

### 2. 启动应用
双击 **`english_learning.html`**，在任意现代浏览器（推荐 Chrome / Edge / Firefox）中打开。无需安装，无需服务器。

### 3. 配置 API
1. 点击一张**预设卡片**（或选择 *自定义*）。
2. 填入 **API Key**，确认 **Model Name**。
3. 点击 **🔌 测试连接** → 成功后点击 **💾 保存配置**。

### 4. 开始学习
- 在文本框输入单词/短语（如 `apple`、`hello world`）或中文（如 `苹果`）。
- 点击 **🔍 学习单词** → 出现结构化学习卡片。
- 使用 **🔊 语音发音** 面板，正常或慢速朗读。
- 每次查询会自动保存到**学习历史**。

### 5. 导出今日笔记
点击 **💾 保存今天内容**。浏览器会下载两个以 **UTC+8** 时间戳命名的文件：

```
2026-06-19_14-30-45-英语学习笔记.md
2026-06-19_14-30-45-英语学习笔记.html
```

- **Markdown** 文件包含目录、信息表格、例句、同反义词、记忆技巧 —— 非常适合导入 Obsidian / GitHub / VS Code。
- **HTML** 文件是自包含的样式页面，可随处打开或打印为 PDF。

> ⚠️ 若浏览器拦截了第二个文件下载，请允许该页面弹出窗口（两次下载间隔 500ms，是为了规避部分浏览器对"连续下载"的拦截）。

---

## 🧠 工作原理

1. 应用将学习者输入发送到所配置的大模型，系统提示词要求返回**严格 JSON 结构**：
   ```json
   {
     "word": "", "phonetic_uk": "", "phonetic_us": "", "part_of_speech": "",
     "chinese_meaning": "", "english_definition": "", "usage": "",
     "examples": [{"en": "", "zh": ""}],
     "synonyms": [], "antonyms": [], "memory_tip": ""
   }
   ```
2. JSON 被解析后渲染为带动画的**结果卡片**。
3. 每条结果保存到 `localStorage`（`learningHistory`，最多 50 条）。
4. 导出时，利用专用提取函数（`extractText`、`extractSection`、`extractExamples`）将保存的 HTML 卡片重新解析为干净的 Markdown / 独立 HTML。

---

## ⚙️ 技术细节

- **技术栈：** 原生 HTML + CSS + JavaScript。无框架、无构建工具、无任何依赖。
- **数据持久化：** 浏览器 `localStorage`（API 配置、会话、历史）。
- **语音朗读：** Web Speech API（`SpeechSynthesis`）。
- **文件导出：** `Blob` + `<a download>` 触发浏览器原生下载。
- **时间戳：** 所有导出文件名与"今天"判定均使用 **UTC+8（北京时间）**，与主机时区无关。

---

## 🔒 隐私说明

- 你的 **API Key** 仅存储在**浏览器本地**的 `localStorage` 中，并且只会发送到**你配置的 API 接口**。
- 项目**不含任何第三方追踪、统计或遥测**代码。
- 所有学习历史仅保存在本地设备。清除浏览器数据即会清除全部内容。

---

## 🛣️ 路线规划

后续版本设想：

- [ ] 艾宾浩斯间隔重复（SRS）复习模式
- [ ] 导入 / 合并之前导出的 `.md` 笔记
- [ ] 深色模式
- [ ] 离线词典兜底
- [ ] 多语言界面

---

## 🤝 参与贡献

欢迎贡献！你可以：

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交修改
4. 发起 Pull Request

请尽量保持"单文件、零依赖"的设计理念。

---

## 📄 开源协议

本项目基于 **MIT License** 开源 —— 详见 `LICENSE` 文件。可自由使用、修改和分发。

---

## 🙏 致谢

- 为小朋友们而打造 🧒📚
- 灵感来自 OpenAI Chat Completions API 规范
- 感谢所有开源大模型提供方（OpenAI、Ollama、硅基流动、DeepSeek）

---

<div align="center">

**✨ 用心打造 · 坚持学习，不断成长！✨**

`v4.0`

</div>