Skip to content

About

AI-powered English intensive reading generator - turn any English article into an interactive learning page

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

📖 英语精读生成器(english-reader)

任何英文文章 → 交互式精读学习页面。本地运行,支持 PC 和手机(同一 WiFi)。

功能

  • 提交文章:粘贴网页网址自动抓取正文(或直接粘贴文本)
  • 大模型自动生成:生词表(三级分级+音标+释义+文中含义+原句例句)、短语搭配、专有名词背景注释、段落中文大意、阅读理解题、长难句解析
  • 交互精读:点击任何单词/短语弹词条卡;核心词蓝色虚线、短语金色虚线标注
  • 四级查词:预生成词条 → 专有名词背景 → 功能词提示 → 大模型实时查询(点击未收录词自动生成,结果缓存)
  • 💬 AI 问答:选中文字后点「询问」,右侧滑出对话面板,可与 AI 多轮追问单词用法、语法、句子结构(词条卡里也有「深入提问」入口)
  • 朗读(TTS):点击单词发音、鼠标/长按划选句子或段落朗读、整段朗读按钮;微软 Edge 云语音(免费、无需 key),失败自动回退浏览器语音
  • 生词本 + 间隔复习 + 测验 + 统计:生词本保存在服务端,跨文章、跨设备(手机收藏的词 PC 上也能复习)
  • 阅读进度打卡、字号调节、标注开关

快速开始

cd english-reader
npm install
copy .env.example .env      # Windows;Mac/Linux 用 cp
# 编辑 .env,填入 LLM_API_KEY(见下)
npm start

启动后终端会打印本机和手机访问地址(含二维码),手机扫码即可使用(需与电脑同一 WiFi)。

端口默认 3000,若被占用在 .env 里改 PORT=3210。

配置大模型(必须)

项目使用 OpenAI 兼容接口,默认配置为 DeepSeek:

  1. 打开 https://platform.deepseek.com 注册,充值少量金额(一篇 3000 词文章全量生成约 ¥0.02-0.05)
  2. 创建 API Key
  3. 填入 .env:
    LLM_BASE_URL=https://api.deepseek.com/v1
    LLM_API_KEY=sk-你的key
    LLM_MODEL=deepseek-chat
    

换其他兼容服务只需改这三个变量,例如智谱(有免费模型):

LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
LLM_API_KEY=你的key
LLM_MODEL=glm-4-flash

使用 Ollama 本地模型(免费、离线)

  1. 安装 Ollama 后拉一个中文能力较好的模型:ollama pull qwen2.5:3b-instruct(1.9GB,16GB 内存即可);显存/内存充裕可用 qwen2.5:7b,效果更好
  2. 打开设置页(首页右上角 ⚙️)→ 点「Ollama 本地」预设 → 点「🔍 获取模型列表」选择已安装的模型 → 保存即可,无需任何 API key
  3. 模型选择要点:用指令微调(instruct)模型;不要用视觉模型(如 minicpm-v)或思考型模型(如 deepseek-r1)——前者结构化输出能力弱,后者在 4096 默认上下文中思考会耗尽输出预算。程序已自动处理:检测到 Ollama 时改走原生接口(禁用思考、单次请求上下文提升到 8192)
  4. 本地小模型生成结构化内容仍有概率性失败:页面会显示失败项和「重新生成」按钮,点一下重试即可;追求稳定质量建议改用 DeepSeek
  5. 排查模型输出问题:启动时加 DEBUG_LLM=1(如 DEBUG_LLM=1 npm start),原始输出会写入 data/llm-debug.log

也可以直接在 .env 里配置:

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL=qwen2.5:3b-instruct

手机访问

  1. 电脑上 npm start,终端显示手机访问地址(如 http://192.168.1.5:3000)和二维码
  2. 手机连同一 WiFi,扫码或输入地址
  3. Windows 首次启动会弹防火墙提示 → 勾选「专用网络」并允许

目录结构

server.js            # Express 入口 + API
lib/fetchDoc.js      # 网页抓取、正文清洗分段
lib/llm.js           # OpenAI 兼容客户端(JSON 容错解析+重试)
lib/generate.js      # 词表/大意/理解题/长难句 生成流水线
lib/tts.js           # edge-tts 语音合成 + mp3 缓存
lib/store.js         # JSON 文件存储(文档/生词本)
public/              # 前端(文档库 + 阅读器)
data/                # 生成的文档、生词本、语音缓存
.mockllm.js          # 本地假 LLM,无 key 时可用它测试全流程

常见问题

  • 生成一直 pending / 报错:检查 .env 的 key 是否填对;服务启动时未配置会在页面顶部提示
  • 某网站抓取失败:部分网站禁止程序抓取,切换「粘贴文本」模式
  • 朗读没声音:edge 语音需要联网;公司网络可能拦截,此时会自动用浏览器语音兜底
  • 无 key 想先体验:node .mockllm.js 起本地假 LLM,.env 里 LLM_BASE_URL=http://localhost:3999/v1、LLM_API_KEY=test,即可走完整流程(内容为占位数据)

数据与隐私

所有数据保存在本机 data/ 目录;文章正文和生词会发送给你配置的大模型服务用于生成内容,不经过任何第三方。

About

AI-powered English intensive reading generator - turn any English article into an interactive learning page

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages