小学AI学习岛工作台建造大师

概述

AI 学习岛建造术（Study Island Builder）

把一个真实上线、真实收费运营过的 AI 学习产品，从定位、数据、前端、AI、语音、后端、部署到质检的全部做法蒸馏成可复用的建造流程。照着做，能避开我们踩过的每一个坑。

0. 先定产品形态（别跳步）

产品一句话：突出 AI 协助学习——入学测评找薄弱点 → 生成针对性学习路径 → 每课「AI 讲 → 练一练 → AI 考考」→ 错题进错题本并分析错因 → 家长看板看进度和用量。

两种交付形态，按阶段选：

• 一期（纯前端）：一个单文件 HTML（本站最终约 210KB），静态托管即可发布，进度存 localStorage。适合先验证产品、快速上线。
• 二期（加后端）：Node + Express + 内置 SQLite，前端同一份文件同源部署。后端提供：账号注册登录、云端进度同步、AI 接口代理（key 收进服务端）、token 用量计量、VIP 手动续费管理端、云端语音代生成。

诚实边界（必须写进产品说明）：高年级/全量课程的讲解是「AI 按课标现场生成」，不是逐课人工定稿；个别课文标题、单元增删要对照实体教材校对。把边界说在前面，是这类产品能长期卖的前提。

1. 课程目录数据化（产品的骨）

1. 目录来源：以现行教材官方目录为准（如人教版 2024 / 语文统编版），逐年级、逐册、逐单元重建，不要凭记忆编目录。本站规模参考：一至六年级 158 个单元、716 个课时 + 一年级深度课 42 课。
2. 双轨内容：低年级（或核心年级）做「深度课」——逐课手写讲解与题库；其余年级做「目录课」——目录是真的，讲解与练习由 AI 按课标现场生成，功能体验与深度课一致。
3. 双模式导航：
   • 按课时顺序：年级 → 册别 → 单元 → 课时；
   • 跨年级关联：把同一知识主题（如数学的「分数」「面积」「方程」）串成主题链（STRANDS），课内提供「上一站 / 下一站」卡片，让补弱的学生能逆流找到前置知识。
4. 数据结构：目录用一份 JS 数据（年级/册/单元/课时四级），课时字段至少含：id、标题、类型（讲课/练习/通关测）。详见 references/课程目录数据结构.md。

2. 单文件前端架构

• 视图：首页（Hero 主视觉）/ 学习路径 / 课程页（AI 讲课区）/ 练习与考考 / 错题本 / 家长看板 / 登录页。全部在一个 HTML 内切换，无构建工具。
• 本地状态 key 设计（本站实际用例，照抄即可）：进度 gk1_v1、年级 gk1_grade、册别 gk1_sem、模式 gk1_mode、登录 token gk1_token、语音来源 gk1_tts_src、发音人 gk1_voice、语速 gk1_rate。进度 key 一旦上线不要改名，改名 = 全体用户进度清零。
• 同源自动检测：前端启动时探测同源 /api 是否存在——有后端才显示登录入口并启用云同步与 AI 代理；无后端自动降级为纯本地模式（静态托管照样能用）。一份文件，两种部署。
• 响应式双端：同一套代码，≥960px 切桌面排版（底部导航变左侧边栏、内容多列），<960px 保持手机竖屏。
• 首页铁律（真实改版教训）：首屏只留一个主角（Hero），登录不挡路（提供「先不登录，随便逛逛」），统计数据全为 0 时隐藏统计区，年级/册别/模式开关收进一个弹层、顶栏只留一个小入口。

3. AI 能力层（产品的魂）

• 调用方式：一期可前端直连大模型 API（key 放在文件顶部配置区，必须同时在服务商后台设额度上限）；二期起一律走服务端 /api/ai 代理，前端永不持有 key。红线：key 绝不能出现在任何公开静态文件里——本站一期曾把 key 写进公开的 config.js，等于明文泄露，发现后立即换新 key 并改架构。
• 讲课：提示词带年级感知（同一年级讲法、词汇量、生字量都不同），结构固定为：导入 → 讲解 → 例题 → 小结。模板见 references/提示词模板.md。
• 出题：要求模型输出结构化 JSON（题干/选项/答案下标/解析），前端解析渲染；temperature、max_tokens 由后端透传（长讲解 max_tokens 给到 3000 量级，防截断）。
• 题目准确性流水线（本产品最值钱的一段）：AI 出的题不能直接给学生用。流程 = 出题模型生成 → 第二个模型以「复核员」身份逐题验算答案与解析 → 不一致的打回重出 → 通过才入库/呈现。静态题库另做全量审计脚本逐题核对。
• 错题本：记录错题 + AI 错因分析 + 「同类练」（按错题知识点再生成同类题）。

4. 题目工程的头号大坑：洗牌必须重映射答案

复制题目并打乱选项顺序时，答案下标（ans）必须跟着选项一起重映射。本站真实事故：cloneShuffle 只洗了选项没改 ans 下标，导致静态题库约 75% 的题目答案错位——学生选对了判错。修复后把「洗牌后逐题校验 ans 指向的选项文本 == 原正确答案文本」写成自动测试，永久防回归。凡是做题库类产品，这一坑必查。

5. 语音朗读（TTS）：直接给终局方案

结论先行：浏览器直连 Edge TTS 这条路不要走。 微软已切换 Sec-MS-GEC v2 握手校验，握手需要浏览器无法设置的请求头（扩展 Origin、Cookie、特定 UA），在华为/QQ/系统自带浏览器上全部被拒。旧 token 方案也会突然失效。

终局架构（三级路由）：

1. 本地有中文发音人 → 用本地语音（Web Speech API）；
2. 本地没有 → 走服务端 /api/tts 代生成（服务端用 ws 库带全套握手头调 Edge TTS，返回 mp3，前端只发普通 HTTPS 请求，无 WS 握手问题）；
3. 服务端另设 /api/tts-test 自检接口（查声音列表 + 试合成），部署后先打这个接口验通。

家长看板提供「语音来源」三档开关（自动/仅本地/仅云端），默认自动。服务端合成结果做内存缓存（本站上限 300 条）。

朗读文本预处理：

• 朗读前剥离 emoji 和符号（不然会把表情读出来）；
• 分句切分、逐段合成连播，单段失败自动跳过不断整段；
• 拼音教学专用处理见下条。

拼音与声调（本站耗时最久的一课）：

• 音节锚定表：TTS 读拼音音节不可靠，必须给每个标准音节配一个同音字锚点（如 mā → 妈），读锚点字代替读字母。本站全量覆盖 410 个标准音节逐个单字锚定；锚点缺失时引擎会把音节拆成两个字读（如 tian → 提+安），且锚点本身要逐个核对（曾出现 c、ong、ao、wu 四个错锚）。
• 声调朗读不要用「示范字」法：用「啊/哦/鹅」这类字示范四声是错的——这些字 TTS 默认读一声，学生点 á 听到的是「二声，啊」，听起来就是一声。最终方案：带调字母直接读字母本身（á、à 实测调型正确；ā 尾音略塌、ǎ 拐弯不完整是引擎硬伤，要如实接受）。选型方法：录多个方案的样本 + 画音高曲线实测，让真实用户听选，不要凭感觉定。
• 声母用呼读音（如 b → 波），完整音节走锚定表，单韵母与带调字母直读——三条规则分开，不要一刀切。

6. 后端：账号、同步、VIP、用量（一台小服务器就够）

技术选型：Express + Node 内置 node:sqlite（零原生依赖。不要选需要编译的 sqlite3 类包——目标机器上没预编译包会被迫现场编译，是部署第一大坑）。密码用 bcryptjs 哈希。

接口清单（本站实际上线版）：

• 账号：POST /api/register、POST /api/login、POST /api/logout、GET /api/me
• 进度：GET/POST /api/progress——同步合并规则：按 updatedAt 新者优先，不要整表覆盖
• AI：POST /api/ai——校验登录、透传参数、逐次记录 token 用量（用户、时间、prompt/completion tokens）
• 家长查账：GET /api/my-usage——本月 + 累计的调用次数、Token 数、按单价折算金额
• 语音：GET /api/tts、GET /api/tts-test
• 管理端：/api/admin/login、用户列表、手动建号、POST /api/admin/extend（续费 +30/+365/自定义天数）、用量统计、Token 单价设置（元/千 Token，存 settings 表，前后台共用）

收费模式建议：手动续费起步（管理后台点一下开通），不接在线支付——对小团队，支付接入的合规与维护成本远大于手动开几十个号。收费结构可做「固定维护费 + 用量加价」，用量看板就是定价的底气。

VIP 到期体验细节：到期遮罩上加「已续费？点我刷新状态」按钮，点击重新调 /api/me 核对——真实事故是运营在本地后台续了费、用户连的却是云端，遮罩不消失。双环境（本地/云端）意识要刻进运营手册。

7. 部署：静态托管 + Windows 云服务器双路线

• 静态站：单文件替换发布即可（托管平台原样替换 HTML，网址不变）。注意：让发布方原样替换，不要让托管平台的 AI 再加工文件。
• 云服务器：腾讯云轻量 4 核 4G 足够。下单前先确认实际系统——本站实例名写 Ubuntu、实际装的是 Windows Server，整条部署路线因此重做。
• Windows 免安装包做法：包内带 runtime/node.exe（免安装 Node），一个「安装并启动.bat」做完三件事：放行 Windows 防火墙端口、用 schtasks 注册开机自启、启动服务并跑自检。轻量云只有「防火墙」没有「安全组」，端口在控制台防火墙里放行。.bat 文件必须 CRLF 换行。
• .env 必坑：服务代码要启动时自动加载同目录 .env（环境变量优先）。只读系统环境变量的写法，会让双击 bat 启动的用户直接撞上「未设置管理员密码」的报错。
• 路径必坑：解压时多套一层以压缩包命名的文件夹，是本站真实事故——后续所有更新都传错了层、线上一直是旧版。部署完成后把真实安装路径写进运营手册，更新时逐字对照。
• 退出远程桌面时只断开连接，不要注销/关机，也不要关掉服务窗口。

8. 上线验版制度（本站用最贵学费换来的规矩）

任何更新，「本地改完」永远不算完成。完成 = 线上验过。

1. 更新后从公网抓线上文件，与本地比对 md5，一致才算传对；
2. 打自检接口（如 /api/tts-test）确认新后端生效；新接口返回 404 = 还是旧版；
3. 让真实用户用真实设备（手机流量、目标浏览器）点一遍核心功能；
4. 多副本同步：主文件、服务器 public、部署包三处的 md5 保持一致；更新文件包用「文件名即目标名」的三件套（index.html / admin.html / server.js），免改名、免传错。

9. 质检：七套回归测试的做法

本站沉淀的回归套件构成（每套都是可重复跑的脚本，改任何东西后全跑）：

1. 题目测试：题库渲染、作答判分、洗牌答案重映射校验；
2. 年级测试：各年级目录加载、课时计数与数据完整性；
3. 错题测试：错题入本、同类练生成、清除；
4. 图形题测试：图形/表格类题目的渲染与答案；
5. 拼音锚点测试：410 音节锚点全量覆盖 + 声调直读规则；
6. 响应式测试：双端布局切换点、导航形态；
7. 云端测试：有/无后端双模式、登录流、语音三级路由、用量记账金额核对（造一笔已知用量，查账金额分毫不差才算过）。

原则：先有失败测试，再修 bug，修完测试转绿才交付；金额、答案这类事不许靠眼看。

10. 砍功能的勇气

• 跟读打分砍掉：浏览器语音识别在目标设备上不可靠，做出来就是假功能，宁可不做。本站完整开发后整体删除。
• 功能取舍标准：核心链路（讲→练→考→错题→家长可见）之外的功能，上线前一律先问「坏了会不会误导学生」，会，就砍或降级。

使用这个 Skill

对 WorkBuddy 说：「用学习岛建造术，帮我做一个 XX 学科 / XX 年级的 AI 学习工作台，先出一期纯前端版」即可。它会按上面 0→9 的顺序推进：先定定位与目录数据，再写前端，再接 AI 与语音，最后给部署与验版清单。配套文件：

• references/课程目录数据结构.md——目录与主题链的数据结构示例
• references/提示词模板.md——讲课 / 出题 / 复核 / 错因分析四套模板
• references/后端接口清单.md——接口表与同步、计费规则
• references/踩坑清单.md——12 个真实坑：现象 → 真凶 → 修法
• references/部署与验版清单.md——双路线部署步骤与上线检查表

不包含什么（先说清）

不含任何真实教材原文、题库数据、API key、服务器信息；课程内容要按目标教材目录自行组织或由 AI 按课标生成后人工校对。本 Skill 卖的是被真实项目验证过的方法、结构、模板和避坑清单。