📘 大学英语速记 · AI 助教

一个面向大学生的 AI 英语学习对话助手：背单词、攻语法、拆长难句、写作文、刷考试技巧，全部用互动卡片呈现，边说边练。

• 纯前端：HTML5 + CSS3 + JavaScript，无需构建、无需后端。
• AI 驱动：调用 GitCode AI 的 DeepSeek-V4-Flash 大模型，SSE 流式输出，打字机体验。
• 结构化返回：通过系统提示词约束 AI 以 JSON 返回结构化数据，前端渲染成「单词卡 / 语法卡 / 自测题」等精美卡片，比纯文字更利于记忆。
• 零依赖：仅浏览器原生 fetch + ReadableStream，开箱即用。

---

✨ 功能特性

类别	说明
📚 单词速记	一次 6 个高频词，带音标、例句、词根/谐音/联想记忆法
🧩 语法解析	定从与非谓语、虚拟语气、时态对比等，规则 + 例句讲清
✂️ 长难句剖析	考研/四六级长难句：主干、修饰、翻译逐层拆解
📝 写作模板	万能作文模板 + 万能句型，应试直接套用
🎯 考试技巧	四六级、考研真题技巧与高频考点串讲
🔎 自测互动	每次回复附带 1 道自测题，点击选项即时对答案
💬 自由问答	非英语问题也能正常闲聊（降级为文本展示）

🖥️ 界面预览

顶部 Logo + 在线状态 → 中部聊天气泡与结构化卡片 → 快捷提问按钮（一键速记/语法/长难句/作文）→ 底部输入框。

• 用户消息：右侧蓝色气泡
• AI 回复：左侧白色气泡 + 彩色类型标签 + 词汇卡片 + 记忆技巧 + 自测题
• 移动端自适应（Responsive）

🚀 快速开始

1. 准备 API Key

本项目需要 GitCode AI 平台的 API 令牌（Bearer Token）。

1. 在 GitCode AI 平台注册并创建令牌；
2. 复制示例配置并填入密钥：

cp js/config.example.js  js/config.js

然后编辑 js/config.js：

window.CONFIG = {
  API_URL: "https://api-ai.gitcode.com/v1/chat/completions",
  API_KEY: "你的令牌",   // 👈 在此填入
  MODEL: "deepseek-ai/DeepSeek-V4-Flash",
  MAX_TOKENS: 2048,
  TEMPERATURE: 0.6,
  TOP_P: 0.95,
  FREQUENCY_PENALTY: 0,
  THINKING_BUDGET: 2048
};

⚠️ 安全提示：js/config.js 已被 .gitignore 忽略，不要把真实密钥提交到 Git 仓库。

2. 运行

直接双击 index.html 即可打开（推荐用本地静态服务器避免浏览器限制）：

# 任选其一
python3 -m http.server 8080 --directory .
# 或
npx serve .

浏览器打开 http://localhost:8080，点击快捷按钮或输入问题，回车发送。

🧠 AI 系统提示词（JSON 协议）

js/system-prompt.js 中定义了系统提示词，强制模型每次以固定 JSON 返回（见文件内完整定义）。核心结构：

{
  "type": "word | grammar | sentence | writing | exam | other",
  "title": "标题",
  "summary": "一句话总结",
  "cards": [
    {
      "head": "主词/语法点",
      "phonetic": "音标",
      "meaning": "释义/讲解",
      "example": "英文例句",
      "example_cn": "例句翻译",
      "memory_tip": "速记技巧（词根/谐音/联想）"
    }
  ],
  "tips": ["拓展技巧1", "拓展技巧2"],
  "quiz": {
    "question": "自测题",
    "options": ["A. ...", "B. ...", "C. ...", "D. ..."],
    "answer": 0,
    "explain": "答案解析"
  }
}

前端 js/render.js 根据 type 渲染对应样式卡片，并实现自测题交互。

📁 项目结构

├── index.html              # 页面入口
├── favicon.svg             # 站点图标
├── css/
│   └── style.css           # 全局样式（含卡片/自测题/响应式）
├── js/
│   ├── config.example.js   # 配置模板（复制为 config.js 使用）
│   ├── config.js           # 本地配置（含 API Key，不入库）
│   ├── system-prompt.js    # AI 系统提示词（JSON 协议约束）
│   ├── render.js           # JSON → HTML 卡片渲染 + 自测题交互
│   └── app.js              # 聊天逻辑：fetch 流式 + 解析 + 渲染
├── .gitignore              # 忽略本地密钥配置
└── README.md

🔄 流式接口说明

Python 示例：

for line in response.iter_lines():
    if line.startswith(b"data:"):
        yield json.loads(line.decode().lstrip("data:"))

JavaScript 实现（js/app.js 中的 streamQuery）：

const response = await fetch(API_URL, { method: "POST", headers, body });
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
// 每次读到 chunk 后按行切分，过滤 "data:" 前缀，
// 遇到 "data: [DONE]" 停止，逐条 JSON.parse 取 delta.content 累加

🛠️ 常见问题

问题	解决办法
请求失败 / 401	检查 js/config.js 的 API_KEY 是否有效
跨域被拦（CORS）	请在本地起服务运行（python3 -m http.server），或部署到支持 CORS 的静态空间
直接用 file:// 打开异常	浏览器不允许部分 API，请用本地服务器方式打开
AI 偶尔返回非 JSON	前端已自动降级为普通文本展示，不会崩溃

📄 License

MIT License © zhjdwk1018