Skip to content
zhyhades7Public

About

在英语的世界里自由冒险

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

纸上冒险(AI 英语冒险阅读小程序,原名"天天英语 TT-ENG")

复刻自抖音「滚雪球日记」介绍的一款英语学习游戏:基于"可理解输入 (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 就行。

第二步:用微信开发者工具打开小程序

  1. 下载安装微信开发者工具(如果还没装)
  2. 打开工具 → 导入项目 → 项目目录选 tt-eng 这个文件夹(注意是这个根目录,不是 miniprogram 子目录,因为 project.config.json 在根目录,里面配置了 miniprogramRoot)
  3. AppID 目前用的是占位值 touristappid,可以直接用"测试号"或游客模式跑,只能在电脑上的模拟器/预览里看效果,不能生成手机扫码的正式预览
  4. 重要:点右上角「详情」→「本地设置」,勾选「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」—— 因为开发阶段小程序要请求 http://127.0.0.1:8787 这个本地地址,不勾这个会被拦截
  5. 确保上一步的后端服务(npm start)还在跑,然后点击工具里的「编译」,就能在模拟器里体验了

想在手机上扫码体验?

你说过愿意去注册,流程很快,不需要营业执照:

  1. 打开 https://mp.weixin.qq.com/wxamp/sandbox/entry(微信小程序"测试号"申请页),用你的微信扫码登录,几秒钟就能拿到一个测试用的 AppID + AppSecret
  2. 把这个 AppID 填进 project.config.json 里的 "appid" 字段,替换掉 touristappid
  3. 注意:测试号默认限制"网络请求的合法域名"必须是备案过的 HTTPS 域名,127.0.0.1 本地地址在真机上是访问不到的。要在真机上体验真实 AI 剧情,需要把 server/ 部署到一台有公网 HTTPS 地址的服务器上(哪怕是最便宜的云主机 + 免费证书都行),然后把 miniprogram/utils/api.js 里的 BASE_URL 改成那个地址,并在小程序后台「开发管理 - 开发设置」里把这个域名加进「request合法域名」
  4. 如果暂时不想折腾部署,也可以先只在电脑开发者工具里用,不影响体验完整功能

难度分级

在 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 后端,原生微信小程序前端

内容安全说明(面向 14 周岁以下用户)

这个小程序主要给中小学生用,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 里加一个难度参数,让小程序端传回最近的复习正确率

About

在英语的世界里自由冒险

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages