ChinaStudyFree · 小学全科 AI 学习平台

一个免费、开源、纯公益的小学全科学习平台

我们相信：每一个中国孩子，无论身处北上广深，还是大山深处的乡村小学，都应该拥有一样好的学习资源。

让孩子在玩中学，让 AI 方便你我他。 ❤️

🌱 项目愿景

中国的教育资源分布不均是一个长期存在的问题。一线城市的孩子可以购买数百元一套的教辅、上价格高昂的补习班；而偏远地区的孩子，往往连一本配套练习册都难以获得。

ChinaStudyFree 希望借助 AI 的力量，改变这件事：

📚 覆盖小学全科：语文、数学、英语、科学
🆓 永久免费：不收费、不卖课、不做广告、不收集隐私
🤖 AI 原创题目：基于人教版/统编版教材知识体系，由 AI 生成单元小测与知识点全解
🔊 全站语音：题目、选项、知识讲解均配有 TTS 语音朗读
📖 课文听读：语文/英语课文逐句跟读，配合课本原页展示
📚 课外故事：AI 生成 284 篇分级读物 + 阅读理解题 + 配图，巩固课内知识
🎮 在玩中学：题目形式生动、即时反馈，让孩子在闯关和互动中建立对知识的兴趣
🌏 服务每一个孩子：从一年级到六年级，只要有一台能上网的设备，就能用

📸 功能预览

Web 端

年级选择	学科总览	学习路径
单元答题	课文听读	课外故事
错题回顾	个人中心

iOS 端

学习路径	答题反馈	商店	我的
课文听读	错题本	每日任务 · 周报	深色模式

全部 12 张界面截图与说明见 docs/ios-ux-gallery.html（本地打开即可，支持点击放大）。

✨ 主要特性

功能	说明
单元小测	跟着课本章节走，学完一课就能练
知识点全解	每个知识点配有清晰讲解、核心概念、公式与易错点
课文听读	语文/英语课文逐句朗读，支持跟读练习，展示课本原页
课外故事	每单元 2 篇 AI 分级故事 + 阅读理解题 + 儿童插画配图
全站 TTS	题目、选项、讲解、故事文本均可点击朗读（Opus 格式，71,500+ 音频）
学习进度	自动保存每课完成情况与正确率，故事阅读支持星星评级
连击系统	连续答对触发连击动画与语音激励

覆盖学科与版本：

学科	版本	年级	课外故事
数学	人教版	一至六年级	—
语文	统编版	一至六年级	188 篇
英语	人教版 PEP	三至六年级	96 篇
科学	教科版	一至六年级	—

🚀 快速开始

1. 克隆仓库

git clone https://github.com/wuwangzhang1216/ChinaTextbookStudyFree.git
cd ChinaTextbookStudyFree

2. 下载资源文件

音频、配图、课本原页和题库数据体积较大，通过 GitHub Release 分发，不包含在 Git 仓库中。

# Linux / macOS / Git Bash (Windows)
bash scripts/download-assets.sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File scripts\download-assets.ps1

这会自动下载并解压以下文件：

文件	内容	大小	解压到
`audio.tar.gz`	71,502 个 TTS 音频 (Opus)	~870 MB	`apps/web/public/audio/`
`story-images.zip`	284 张 AI 故事配图	~368 MB	`apps/web/public/story-images/`
`textbook-pages.zip`	1,577 张课本原页 (JPG)	~192 MB	`apps/web/public/textbook-pages/`
`data.zip`	前端构建数据 (JSON)	~4.3 MB	`apps/web/public/data/`
`data-source.zip`	passages + stories 源 JSON	~811 KB	`data/`

3. 运行 Web 端

cd apps/web
npm install
npm run dev

访问 http://localhost:3000 即可。

4. 运行 iOS 端

需要 macOS + Xcode 16+ + XcodeGen：

brew install xcodegen      # 首次安装
cd apps/mobile
xcodegen generate          # 生成 .xcodeproj
open ChinaTextbookStudy.xcodeproj

在 Xcode 里选 iPhone / iPad 模拟器，Cmd+R 即可运行。App 内置一本数学书（一年级上册 + 第一节课的 TTS 音频）作为离线种子，无需网络就能体验完整流程。

iOS 端特点：

SwiftUI 原生（非 React Native），支持 iPhone + iPad（iPad 自动分栏布局）
域逻辑（SRS / 判分 / 成就 / 宝箱 / 吉祥物）从 packages/core 逐文件对译为 Swift
音频：Opus 预转码为 AAC m4a，AVAudioPlayer 播放，无第三方解码依赖
数据按书从 GitHub Release 按需下载（首启不需要下完全部 44 本的 ~843MB）
38 个单元测试 + 11 个 UI 测试（答题闭环、退出确认、标签导航、装扮购买、每日任务）

统一设计系统（DesignSystem/）

全端共用一套令牌，没有任何页面掉回原生系统控件：

令牌	内容
`DuoColors`	品牌色 + 语义色（`bg` / `surface` / `border` / `ink`…），浅色为主、深色为可选，同一份代码自动适配
`DuoFont`	圆体字号角色（display / title / heading / body / caption…），根部统一 `.fontDesign(.rounded)`
`DuoLayout`	`Space` / `Radius` / `Motion` 三组令牌，全局共用一套动效曲线
`DuoButtonStyle`·`DuoCardStyle`	标志性的立体「下沿」按压质感

学习体验

路径即首页：当前节点呼吸动效 + 真实单元进度环，点击弹出开始气泡
答错回炉重练：进度条只在答对时前进，且必定走满；错题自动进入 SRS 错题本
爱心耗尽拦截、退出二次确认、答错震屏与抖卡、每次点选都有触感与音效
结算页连胜与每日达标庆祝；错题复习不扣爱心且奖励经验值
课文/故事支持「朗读全文」逐句高亮跟随，读完奖励经验值
吉祥物「聪聪」（熊猫）以 SwiftUI Canvas 绘制，含呼吸、眨眼与情绪反应

装扮系统（earn → spend → express 闭环）

用学习赚来的宝石购买皮肤 / 主题 / 课程背景，购买即装备
皮肤：11 款配饰（学士帽、圆框眼镜、皇冠、法师帽、宇航员头盔、DJ 耳机…）直接画在聪聪身上，全局生效
主题：10 套配色通过 DuoColors.themeOverride 重绘全局品牌色；深色系主题（暗夜模式 / 曜石黑）自动切换深色外观
课程背景：8 款渐变作用于答题页，按对比度需要自动降低强度，保证题目始终可读
商店里的每个格子都是实时预览：皮肤格是戴着该配饰的聪聪本人，主题格是该主题的真实配色

留存机制

每日任务：每天 3 个不同类型的任务（赚经验 / 完成小课 / 复习错题 / 读课文），由日期做种子确定性生成——同一天任何时候打开都是同一组，且不需要服务端；完成后可领取宝石奖励
本周报告：近 7 天经验值柱状图 + 与上周的增减对比，作为离线版的「和自己比」
连胜提醒：可选的本地通知，每晚 20:00 提醒保住连胜；当天已学习则自动顺延到次日，绝不打扰。默认关闭，在设置里开启时才申请系统授权

更多上架相关细节见 apps/mobile/APPSTORE.md。

5. （可选）运行数据生成 Pipeline

如需从教材 PDF 重新生成题库数据：

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 配置 .env（填入 API Key）

# 生成题库
python scripts/quiz/pipeline.py --subject all

# 生成课外故事
python scripts/stories/pipeline.py --subject all

# 生成故事配图
python scripts/stories/images.py --subject all

# 生成 TTS 音频
python scripts/tts/collect_texts.py
python scripts/tts/api_tts.py

# 构建前端数据
cd apps/web && npx tsx scripts/build-data.ts

🏗️ 项目结构

ChinaStudyFree/
│
├── scripts/
│   ├── quiz/                       # 题库生成 Pipeline
│   │   ├── pipeline.py             #   PDF → 大纲 → 题库
│   │   ├── prompts.py              #   AI Prompt 模板（按学科定制）
│   │   └── subjects.py             #   学科 / 版本 / 年级配置
│   ├── stories/                    # 课外故事生成 Pipeline
│   │   ├── pipeline.py             #   大纲 → 分级故事 + 阅读理解题
│   │   ├── prompts_story.py        #   故事 Prompt 模板 + JSON Schema
│   │   └── images.py               #   Gemini AI 配图生成
│   ├── passages/                   # 课文抽取
│   │   ├── extract_passages.py     #   PDF → 逐句课文 JSON
│   │   └── render_pages.py         #   PDF → 课本原页 JPG
│   ├── tts/                        # TTS 语音合成
│   │   ├── collect_texts.py        #   扫描全部文本，生成待合成清单
│   │   └── api_tts.py              #   DashScope API 批量合成
│   ├── download-assets.sh          # 下载 Release 资源（Linux/macOS）
│   ├── download-assets.ps1         # 下载 Release 资源（Windows）
│   └── package-release.sh          # 打包资源为 Release 附件
│
├── output/                         # Pipeline 产出（大纲 + 题库 JSON）
│   ├── math/chinese/english/science/
│   │   ├── outlines/               #   教材知识大纲
│   │   └── quizzes/                #   单元题库
│
├── data/                           # 源数据（通过 Release 下载）
│   ├── passages/                   #   课文听读源 JSON（语文/英语）
│   └── stories/                    #   课外故事源 JSON（语文/英语）
│
├── packages/core/                  # TypeScript 共享域逻辑（Web 端运行时 + iOS 翻译蓝本）
│
└── apps/
    ├── mobile/                         # iOS SwiftUI 端（iPhone + iPad）
    │   ├── project.yml                 #   XcodeGen 项目定义
    │   ├── ChinaTextbookStudy/
    │   │   ├── App/                    #   SwiftUI @main + NavigationStack/SplitView + 路由
    │   │   ├── DesignSystem/           #   DuoColors / DuoFont / DuoLayout / Button / Card / Effects
    │   │   ├── Models/                 #   CoreTypes.swift（对译 packages/core/types.ts）
    │   │   ├── Domain/                 #   SRS / Grade / Achievements / Chest / Cosmetics / MascotTriggers
    │   │   ├── Services/               #   DataLoader / AssetDownloader / AudioPlayer / Haptic / SFX
    │   │   ├── Stores/                 #   ProgressStore / SettingsStore（持久化）
    │   │   ├── Features/               #   Onboarding / Home / Lesson / Review / Reading /
    │   │   │                           #   Stories / Shop / Profile / Settings / Achievements
    │   │   └── Components/             #   PathMapView / MascotView / BottomTabBar / 反馈与庆祝件
    │   ├── ChinaTextbookStudyTests/    #   38 个单元测试（域逻辑 + 每日任务）
    │   └── ChinaTextbookStudyUITests/  #   11 个 UI 测试（答题闭环 / 导航 / 装扮 / 任务）
    │
    └── web/                            # Next.js 前端（原 frontend/）
        ├── scripts/
        │   └── build-data.ts           #   output/ + data/ → public/data/ 构建
        ├── src/
        │   ├── app/                    # 路由与页面
        │   │   ├── book/               #   教材详情 / 学习路径
        │   │   ├── reading/            #   课文听读
        │   │   ├── stories/            #   课外故事阅读 + 答题
        │   │   ├── lesson/             #   答题页面
        │   │   ├── grade/              #   年级总览
        │   │   ├── profile/            #   学习档案
        │   │   ├── review/             #   错题回顾
        │   │   └── shop/               #   商店 / 奖励
        │   ├── components/             # UI 组件
        │   ├── lib/                    # 工具库（TTS、音效、状态）
        │   ├── store/                  # Zustand 状态管理
        │   └── types/                  # TypeScript 类型定义
        └── public/
            ├── audio/                  # TTS 音频（通过 Release 下载）
            ├── data/                   # 题库+故事 JSON（通过 Release 下载）
            ├── story-images/           # AI 故事配图（通过 Release 下载）
            └── textbook-pages/         # 课本原页图片（通过 Release 下载）

📖 教材来源与版权

本项目引用的教材结构来自开源项目 TapXWorld/ChinaTextbook。

版权策略：

不搬运教材原文，只提取知识大纲与章节结构
所有题目由 AI 原创生成，基于知识点而非教材原题
课外故事为 AI 原创，不抄袭任何已出版读物
如相关版权方认为本项目存在任何问题，请与我们联系，我们会第一时间响应处理

🤝 如何参与

这是一个纯公益项目，我们非常欢迎任何形式的参与：

👩‍🏫 一线老师：帮我们审核题目质量、指出错误、建议题型
👨‍👩‍👧 家长：把平台分享给需要的家庭，反馈孩子的使用体验
💻 开发者：提交 PR 修 bug、加功能、优化 UI
🎨 设计师：帮我们让界面对孩子更友好、更有趣
📣 任何人：把这个项目告诉一所乡村小学的老师

🛣️ 路线图

📜 许可协议

本项目采用 MIT License 开源发布，详见 LICENSE。

💌 写在最后

我们不知道这个项目能走多远，但我们知道，只要多一个孩子因为它而多做对一道题、多理解一个知识点、多喜欢上一门课，这件事就是值得的。

如果你认同我们的理念，欢迎 ⭐ Star 支持，也欢迎把它转发给任何一位你认识的老师和家长。

让每一个中国孩子，都能在玩中学。

Navigation Menu

Repository files navigation

ChinaStudyFree · 小学全科 AI 学习平台

🌱 项目愿景

📸 功能预览

Web 端

iOS 端

✨ 主要特性

🚀 快速开始

1. 克隆仓库

2. 下载资源文件

3. 运行 Web 端

4. 运行 iOS 端

5. （可选）运行数据生成 Pipeline

🏗️ 项目结构

📖 教材来源与版权

🤝 如何参与

🛣️ 路线图

📜 许可协议

💌 写在最后

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
apps		apps
docs		docs
output		output
packages/core		packages/core
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

ChinaStudyFree · 小学全科 AI 学习平台

🌱 项目愿景

📸 功能预览

Web 端

iOS 端

✨ 主要特性

🚀 快速开始

1. 克隆仓库

2. 下载资源文件

3. 运行 Web 端

4. 运行 iOS 端

5. （可选）运行数据生成 Pipeline

🏗️ 项目结构

📖 教材来源与版权

🤝 如何参与

🛣️ 路线图

📜 许可协议

💌 写在最后

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages