AI 英语助教

一个纯前端的英语单词学习应用。无需后端，学习数据保存在浏览器 localStorage；可导入词库、从邮件提词、进行测试和错题复习，并支持可选的 OpenAI 兼容 AI 服务。

仓库包含两个可独立运行的版本：

• src/：当前单文件式实现（index.html、styles.css、script.js）。
• refactor/：ES Modules 重构版；按页面、服务、UI 与样式拆分，保持原有功能和数据兼容。

启动

应用需要通过 HTTP 服务运行，不能直接打开 HTML 文件。

# 在仓库根目录运行
python -m http.server 8000

开发原版 src/ 时，Windows 10 可用仓库根目录的脚本一键控制服务：

python serve.py start   # 后台启动，访问 http://localhost:8000/
python serve.py status  # 查看运行状态
python serve.py stop    # 停止服务

脚本不生成 PID 文件，而是通过 8000 端口识别 src/ 的本地 HTTP 服务；当端口被其他程序占用时，可在提示后选择强制关闭该进程并启动。

打开：

• 原版：http://localhost:8000/src/（使用上述根目录命令）或 http://localhost:8000/（使用 serve.py）
• 重构版：http://localhost:8000/refactor/

也可启动重构版预设脚本：

cd refactor
npm run serve

该脚本会将仓库根目录作为 HTTP 根目录，因此可正确读取根目录的 data/ 词库。两版若要共享已有学习数据，必须使用相同的协议、主机和端口；localStorage 按 origin 隔离。

功能概览

• 单词库：JSON 导入与导出、搜索、分类与收藏筛选、详情和发音。
• 学习与复习：基于 [1, 2, 4, 7, 15, 30] 天间隔的复习计划、错题卡片复习与学习统计。
• 测试：英译中、中译英、本地或 AI 出题、错题与收藏范围测试。
• 邮件学习：从英文邮件提取词汇、批量翻译入库、全文阅读、高亮、朗读与 AI 分析。
• 设置：主题、AI 配置、词库自动加载、完整数据备份与恢复。

技术与外部服务

• 原生 HTML、CSS、JavaScript；重构版使用浏览器原生 ES Modules，无构建步骤。
• Font Awesome、Chart.js。
• Free Dictionary API、Azure TTS、有道 TTS 与浏览器 Web Speech（网络语音不可用时回退到浏览器朗读）。
• OpenAI 兼容 Chat Completions API（可选，用于出题、翻译和邮件分析）。

CDN 或第三方 API 被网络、离线环境或 CSP 阻止时，相应的图标、图表、AI 或网络语音功能会受限。

数据与兼容性

核心数据包括单词、练习记录、复习计划、收藏、邮件、主题与 AI 设置。重构版沿用原版的数据结构，并支持将默认词库的旧键（如 words、records、schedule、favorites）迁移为按词库分组的存储键。

重构版的主要目录：

• refactor/js/core/：状态、存储、路由与事件委托。
• refactor/js/services/：TTS、AI、复习算法、统计、出题、提词与词库服务。
• refactor/js/pages/：各页面和学习流程。
• refactor/js/ui/：主题、侧边栏、Toast、Modal 与 DOM 工具。
• refactor/styles/：按原样式级联顺序拆分的样式文件。

重构版不使用内联事件处理器；交互通过命名空间化的 data-action 和统一事件委托处理。

验收

重构版的手工验收清单位于 refactor/docs/smoke-test.md。验证时请在开发者工具中检查 Console，并确认两版使用同一 origin 后再检查历史数据。

发布与缓存

Linux 服务器可使用 deploy.sh 一键下载并部署 main 分支的最新版本：

• 保留 deploy 参数，以便下载脚本后直接执行部署，而不是进入交互菜单。

bash <(curl -fsSL https://gitea.tohub.top/Share/AI_English/raw/branch/main/deploy.sh) deploy

脚本会将 src/index.html、src/js/ 和 src/styles/ 部署到 /root/data/docker_data/Nginx/html/english/ai/，清理目标目录中的其他内容，但保留已有的 data/ 目录。运行前请确认目标路径符合服务器配置；脚本需要 root 权限以及 curl、tar、find 命令。

src/index.html 通过 CSS 和 JavaScript URL 的 v 查询参数控制静态资源缓存。每次发布修改了 src/styles.css 或 src/script.js，请同步递增对应版本号。服务器应优先为 index.html 设置 Cache-Control: no-cache；带版本号的静态资源可长期缓存。

设置页的“获取最新版本”仅清理应用资源缓存，不应改为清除 localStorage，以免丢失学习数据和 AI 配置。