复刻自抖音「滚雪球日记」介绍的一款英语学习游戏:基于"可理解输入 (i+1)"理论的 AI 互动冒险故事英语学习工具。 这个版本按照孩子的实际水平(高中 - 大学四六级,约 CEFR B1-C1)做了裁剪,去掉了原作里的社区、创作者经济、付费存档等和"给孩子学英语"这个目标无关的部分,保留了最核心的教学机制:
- AI 实时生成互动冒险故事,正文用孩子已掌握的词汇写,每个场景刻意埋几个"高一级"生词,靠上下文就能猜出意思(i+1 原则)
- 三档难度可选:初中 / 高中·四六级 / 雅思·托福,每档对应不同的基础词汇范围和生词来源,在首页选(详见下方「难度分级」)
- 点单词看音标 + 中文释义 + 发音,自动收进"词汇本"(AI 精选的生词是这样;正文里其他没被标成生词的普通单词也能点开查免费词典释义,详见下方「任意单词查询」)
- 词汇本闪卡复习(认识 / 还不熟)
- 中文剧情提示(不是翻译,卡壳了才点开看)
- 没有配置 API Key 时,自动用内置的离线体验故事(五个主题各一篇,见下方「离线体验故事」),小程序照样能完整跑通
- 游戏化激励:每日签到攒 TT Coin、连续学习天数、累计阅读场景数、完成故事随机开出勋章、荣誉殿堂收集图鉴、用 TT Coin 在皮肤商店换整套配色(详见下方「游戏化系统」)
tt-eng/
├── project.config.json # 小程序项目配置(占位 appid,见下方说明)
├── server/ # 后端:调用 LLM 生成剧情
│ ├── server.js
│ ├── lib/
│ │ ├── prompt.js # i+1 教学原则的 system prompt
│ │ ├── llm.js # 调用 DeepSeek(或任意 OpenAI 兼容接口)
│ │ └── fallback.js # 离线兜底故事(无 key / 调用失败时用)
│ └── .env.example # 复制成 .env 并填入你的 key
└── miniprogram/ # 小程序前端(原生 WXML/WXSS/JS)
├── pages/home # 首页:护照式统计头、选主题、看统计
├── pages/story # 故事阅读 + 选择推进 + 勋章开出弹层
├── pages/vocab # 词汇本
├── pages/flashcard # 闪卡复习
├── pages/hall # 荣誉殿堂:勋章图鉴
├── pages/shop # 皮肤商店:用 TT Coin 换配色
└── utils/
├── storage.js # 本地存储:词汇本/统计/签到/勋章/皮肤
├── badges.js # 14 枚勋章图鉴目录
├── skins.js # 5 套皮肤的配色 token 目录
└── theme.js # 把选中的皮肤 token 拼成 CSS 变量内联样式
- 签到 / 连续学习天数:首页"护照卡"每天可以签到一次,领 TT Coin(基础 10 个,连续签到每多一天 +2,封顶 30 个/天)。连续签到会累计"连续学习天数",断签就从 1 重新算。
- 累计阅读量:每读到一个新场景(不管是不是结局)都会 +1,记在首页统计里。
- 勋章 / 荣誉殿堂:一共 14 枚勋章(
miniprogram/utils/badges.js),每完成一次冒险(走到is_ending)就会从"还没集齐"的勋章里随机开出一枚,集满就不再重复发。「荣誉殿堂」页面(pages/hall)能看到全部勋章:已获得的是彩色奖章,没获得的显示灰底问号,点一下会提示"完成一次冒险即可能随机获得"。 - 皮肤商店:
miniprogram/utils/skins.js定义了 5 套完整配色(1 套默认免费 + 4 套需要 TT Coin 购买,80-150 个不等)。「皮肤商店」页面(pages/shop)可以购买/切换,换肤是整站生效的——每个页面顶层 view 都绑了style="{{themeStyle}}",把当前皮肤的配色通过 CSS 变量(--bg/--accent/--gold等)内联下去,所有页面的 WXSS 都是用var(--xxx)写的,所以换皮肤不用一个个页面去改。想加新皮肤,在skins.js里加一条配色 token 就行,不用碰任何页面代码。
cd server
npm install
cp .env.example .env如果你想要真实 AI 实时生成剧情(而不是固定的离线体验故事),去 platform.deepseek.com 注册,充值几块钱(很便宜,几百次对话大概几毛到几块钱),生成一个 API Key,填到 .env 里的 DEEPSEEK_API_KEY。不填的话服务会自动降级成内置的离线故事,小程序依然能完整体验一遍所有功能。
npm start看到 server running at http://127.0.0.1:8787 (mode: LLM) 或 (mode: fallback demo) 就说明启动成功了。
想换成别的模型服务商(比如通义千问、文心一言,只要是 OpenAI 兼容的 chat/completions 接口)也可以,改
.env里的DEEPSEEK_BASE_URL/DEEPSEEK_MODEL就行。
- 下载安装微信开发者工具(如果还没装)
- 打开工具 → 导入项目 → 项目目录选
tt-eng这个文件夹(注意是这个根目录,不是miniprogram子目录,因为project.config.json在根目录,里面配置了miniprogramRoot) - AppID 目前用的是占位值
touristappid,可以直接用"测试号"或游客模式跑,只能在电脑上的模拟器/预览里看效果,不能生成手机扫码的正式预览 - 重要:点右上角「详情」→「本地设置」,勾选「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」—— 因为开发阶段小程序要请求
http://127.0.0.1:8787这个本地地址,不勾这个会被拦截 - 确保上一步的后端服务(
npm start)还在跑,然后点击工具里的「编译」,就能在模拟器里体验了
你说过愿意去注册,流程很快,不需要营业执照:
- 打开 https://mp.weixin.qq.com/wxamp/sandbox/entry(微信小程序"测试号"申请页),用你的微信扫码登录,几秒钟就能拿到一个测试用的 AppID + AppSecret
- 把这个 AppID 填进
project.config.json里的"appid"字段,替换掉touristappid - 注意:测试号默认限制"网络请求的合法域名"必须是备案过的 HTTPS 域名,
127.0.0.1本地地址在真机上是访问不到的。要在真机上体验真实 AI 剧情,需要把server/部署到一台有公网 HTTPS 地址的服务器上(哪怕是最便宜的云主机 + 免费证书都行),然后把miniprogram/utils/api.js里的BASE_URL改成那个地址,并在小程序后台「开发管理 - 开发设置」里把这个域名加进「request合法域名」 - 如果暂时不想折腾部署,也可以先只在电脑开发者工具里用,不影响体验完整功能
在 server/lib/prompt.js 的 LEVEL_PROFILES 里定义了三档,真实 AI 生成时会按选中的难度换用不同的 system prompt:
| 难度 | 对应水平 | 基础词汇 | i+1 生词来源 | 篇幅 |
|---|---|---|---|---|
初中 (junior) |
CEFR A2-B1 | 中考核心1600词 | 初中拓展词/简单高中低频词 | 100-160词 |
高中·四六级 (senior_cet46) |
CEFR B1-C1 | 高考核心词、四级核心词 | 四级以上高频词、雅思托福常见词 | 150-220词 |
雅思·托福 (ielts) |
CEFR B2-C1 | 四六级词汇+雅思托福基础学术词 | 雅思托福高频学术词、地道搭配 | 200-280词 |
想调整某一档的具体标准(比如词汇范围、句式复杂度),直接改 LEVEL_PROFILES 里对应的描述文字就行,不需要改代码逻辑。
没有配置 API Key,或者调用 LLM 失败时,后端会用 server/lib/fallback.js 里内置的五个固定短篇兜底,主角都设定成 18 岁的少年,运行形式和真实 AI 生成的故事一样(选择推进、生词自动进词汇本、6-7 个场景后收尾)。首页五个预设主题各自对应一个专属故事,一一对应、不会撞车:
| 首页主题 | 故事 | 主线 |
|---|---|---|
| 🚀 太空探险 | 星海信号 | 空间站学员追查一枚神秘信号,发现深空中一份古老的"生命讯息" |
| 🌲 奇幻森林 | 回声橡树 | 森林深处的老橡树开口求助,寻找一颗失落已久的守护之光 |
| 🏝️ 无人岛求生 | 废弃灯塔 | 独自登岛寻找祖父留下的秘密,温情向 |
| 🌆 未来都市 | 最后的信号(赛博朋克) | 在反乌托邦都市里追查失踪姐姐留下的加密信号 |
| 🔍 校园悬疑 | 消失的房间(悬疑解谜) | 参加地下解谜游戏,卷入一场多年前的失踪疑云 |
首页点预设标签时会带上主题 ID,服务器直接精确匹配对应故事,不会互相干扰。只有"自定义"主题(自己输入文字)才会退回到关键词粗略匹配(比如写"宇宙飞船"会匹配到「星海信号」,写"荒岛"会匹配到「废弃灯塔」),匹配不中就用「废弃灯塔」兜底。这五个故事目前难度固定在高中·四六级左右,不随首页选的难度档位变化(真实 AI 生成的故事才会跟着难度走)。每个故事都有一个分支点,两条路线各自收向不同的结局。
| 原作 | 这个版本(纸上冒险) |
|---|---|
| Wonder / Odyssey 双模式,含地图/角色/物品三维演算 | 单一的文字冒险模式,聚焦阅读+生词,去掉了游戏化的地图系统 |
| AI 生成配图,图片复用索引降本 | 用色彩渐变代替配图(省去图片生成的成本和复杂度) |
| TTS 语音朗读整段故事 | 只对生词做发音(用有道词典公开发音接口),没做整段 TTS |
| "旅人酒馆"社区、创作者关注、悬赏帖 | 去掉,孩子自己用不需要社交功能 |
| 雪球虚拟货币、存档付费、创作者分成 | 去掉,只留"完成次数 / 生词数"这种轻量统计做正反馈 |
| Python FastAPI + Electron | Node.js + Express 后端,原生微信小程序前端 |
这个小程序主要给中小学生用,AI 生成的故事内容有硬性的年龄适龄性约束,写在 server/lib/prompt.js 的 system prompt 里,对模型强制生效:
- 禁止暴力、血腥、恐怖/惊悚渲染、死亡的具体描写
- 禁止自伤/自杀、毒品/酒精/烟草、赌博相关情节
- 禁止恋爱/暧昧/两性相关情节
- 禁止脏话、骂人的话,以及任何形式的歧视或欺凌描写
- 悬疑/冒险类主题允许保留紧张感和悬念,但要求用"未知""发现""解谜"这种探索感代替恐惧和惊吓,冲突的化解方式必须是勇气、智慧、合作,不能靠暴力手段
- 五篇内置的离线兜底故事(
server/lib/fallback.js)是人工写的固定内容,同样遵循以上标准,不依赖 AI 也能保证安全
提交小程序审核时,如果"服务内容说明"之类的字段需要填内容安全承诺,可以直接参照上面这几条。
- API 入口去掉共享 key 兜底,改成兼容多家服务商:云函数版本(
cloudfunctions/story/llm.js)严格 BYOK,用户没填自己的 key 直接走离线体验故事,绝不消耗服务器自己配置的 key。支持通义千问 / 智谱GLM / Kimi / DeepSeek / 自定义等 OpenAI 兼容服务商,在「我的 API Key」设置页选。(server/lib/llm.js即 Railway 版本保留了共享 key 兜底,那个只给开发者自己家里人测试用,不会公开对外。) - 加用户数据云同步:见下方「用户数据云同步」一节。
换手机、清缓存之后,生词本 / 勋章段位 / 连续学习天数 / 皮肤 / 故事存档 / 收藏夹这些学习进度不会丢——原理:
- 新增了一个云函数
cloudfunctions/userdata,用cloud.getWXContext().OPENID拿到微信侧签发的、无法伪造的用户身份,不需要走传统的wx.login()→ code → 服务端换 openid 那一套流程(云开发环境里调用云函数自带这个身份信息),也不需要用户做任何"登录"操作,对孩子来说完全无感。 - 数据存在云开发数据库的
user_data集合里,一个 openid 一条记录,云函数首次写入时会自动建集合。 - 客户端逻辑在
miniprogram/utils/sync.js:小程序启动时(app.js的onLaunch)把云端数据拉下来盖在本地上,云端还没有数据时不会覆盖本地(保证老用户已经攒的本地进度不会被清空);小程序切到后台时(onHide)把本地最新状态整体推上云。 - 不同步的字段:用户自己填的 API Key(
tt_user_api_config)只留在本机,不会出现在云函数的同步数据里——这是刻意的,跟设置页里"Key 不会上传到任何第三方"的隐私承诺对应。
提交审核前记得在小程序后台的"用户隐私保护指引"里补一条:收集 openid 用于同步学习进度数据(云开发数据库存储)。
AI 只会挑几个"高一级"生词标出来(i+1 原则要求正文其余部分用孩子已掌握的词汇写),但实际读的时候孩子可能对没被标出来的词也不认识。故事页和收藏夹详情页里,正文的每一个单词现在都能点:
- 点中 AI 精选的生词(带下划线高亮的那种):跟以前一样,直接弹出预先生成好的音标/中文释义/例句,并且已经自动进了词汇本
- 点其他普通单词(没有高亮,样式很淡,只有一圈点状下划线提示"这个也能点"):现查一次有道词典的免费接口(
miniprogram/utils/dictionary.js,不需要 key),弹出"词性 + 中文释义",可以点"🔊 发音"或者"➕ 加入词汇本"(存进去时音标/例句留空,跟 AI 精选生词的数据完整度不完全一样,够用即可)
必须做的配置:dict.youdao.com 这个域名要加进小程序后台"服务器域名"里的 request合法域名 白名单(路径:开发管理 → 开发设置 → 服务器域名),不然真机上这个查词请求会被小程序运行时直接拦掉。开发者工具里本地调试不受这个限制影响(除非勾了"校验合法域名")。
- 单词发音用的是有道词典的一个公开接口(非官方 API),长期稳定性不保证,失效了可以换成任何返回 mp3 的 TTS 服务
- 目前没有做"根据孩子答对/答错动态调整难度",如果想要这个可以在
server/lib/prompt.js里加一个难度参数,让小程序端传回最近的复习正确率