congcong-school README

项目的 README,来自 github.com/wuwangzhang1216/congcong-school。合并为一个 markdown 文件:README.md。

聪聪学堂 · 学习,从好奇心开始。小学全科,免费开源。

在线体验:聪聪学堂 · 支持电脑和手机浏览器,无需安装。

版本与资源说明

当前版本 v1.8.3:新增人教版(精通)五年级上册(2026秋版),与 PEP 并列,保留原有教材和成绩。新增6个单元、2节复习、96条词汇、32节小课、216道练习和36道挑战题;词汇、题目与讲解音频齐全,新增847条语音由Edge TTS生成,另复用197条既有音频。听读覆盖单元词汇,不包含全册课文、歌曲或原页点读。来源与范围。继承长数字输入、资源增量更新和续学计时修复。#12的教师、儿童与真机验收仍待完成。

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

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

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


🌱 项目愿景

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

ChinaStudyFree 希望借助 AI 的力量,改变这件事:


产品一览

聪聪与苹果、书本的品牌主视觉

动手练习,即时反馈

iPhone 展示互动点数与答题反馈

通过互动点数和多种题型理解知识,答题后查看解析,随时继续未完成的课程。

课本原页,逐句听读

平板与 iPhone 展示课本原页、全文朗读和跟读

对照课本原页听读,支持全文朗读和跟读练习。

故事阅读与聪聪衣橱

笔记本和平板展示故事阅读、阅读理解与聪聪衣橱

从分级故事到阅读理解,再用学习获得的宝石为聪聪解锁装扮。

海报与截图画廊(下载仓库后本地打开) · 原尺寸 PNG · 素材与重制说明

查看 Web 界面截图

Web · 从第一步开始

手机端年级选择,继续按钮完整可见
找到自己的起点
选择年级,开始探索
点击三个苹果,完成互动点数
亲手数一数
先动手,再理解
答对后显示 10 XP 与具体解析
看懂每一次反馈
知道答案,也知道为什么

Web · 在更大的屏幕上,展开好奇心

桌面端学科总览
全科学习,从容选择
按教材单元展开的数学学习路径
沿着教材,一步一步前进
课本原页与咏鹅逐句听读
课本原页,逐句听读
门口的小伞的插画和分句故事阅读
在故事里,发现新世界
聪聪衣橱的大幅预览与商品卡片
给聪聪,换一种模样
错题本空状态鼓励尝试并提供巩固入口
每一次尝试,都在进步
聪聪的故事时间与分级故事列表
选一个故事,一起读
个人中心、本周报告和成就入口
留下属于自己的学习足迹

iOS 原生界面 · 历史素材

以下保留原有 iOS 截图,与上方新采集的 Web 画面分别标示;本轮未重新运行 iOS 构建。


学习路径

答题反馈

商店

我的

课文听读

错题本

每日任务 · 周报

深色模式

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


✨ 主要特性

功能 说明
单元小测 跟着课本章节走,学完一课就能练
知识讲解 4,480节常规课均有知识讲解,题组每课至少6题;五四制来源与范围
课文听读 语文/英语课文逐句朗读,支持跟读练习,展示课本原页
跟读录音 浏览器内录音与回放,不上传录音;需要 HTTPS 和麦克风授权,暂无语音识别评分
课外故事 每单元 2 篇 AI 分级故事 + 阅读理解题 + 儿童插画配图
全站 TTS 题目、选项、讲解、故事文本均可朗读;完整包提供 119,219 个 MP3 文件;恢复内容对应的音频全部齐备,复用已有 Edge 语音并补齐缺失项,保留原路径兼容资源
首次讲解 进入课程自动尝试播放,听完才解锁下一步;按钮边框光环跟随真实播放进度,不显示秒数
学习进度 当前浏览器保存完成情况、正确率与阅读星级;暂无云端账号和跨设备同步
连击系统 连续答对触发连击动画与语音激励
错题与学习报告 错题复习、每日目标、本周报告与家长每日学习时间限制

浏览器可能限制首次自动播放;可点标题旁的小喇叭恢复播放。静音或播放失败时提供“阅读后继续”。清除浏览器数据会影响本地学习记录。

覆盖学科与版本:

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

当前资源规模(v1.8.3):85册教材版本(71册当前版本、14册旧版兼容),其中六三制59册、五四制26册;4,480个常规课时、635个单元挑战,常规题27,885道、挑战题6,375道,另有1,317篇/组课文和284篇故事。这是资源覆盖统计,不代表所有题目已通过教师逐题审核。

人教精通五上已纳入本版教材与语音资源,独立 ID 为 english-g5up-jingtong-2026;来源、覆盖范围和构建方法见 #62 教材说明。

历史审计状态(v1.4.3,非当前规模):原补齐版的 2,356 课、15,117 道常规题及讲解已恢复;保留 2026 秋版二上数学的 28 课、168 题,以及三节视觉数感示范的 18 题。原数感课的 24 道题另保留为三节巩固练习,旧错题仍可按原记录复习。全库共 2,387 节常规课、15,303 题,缺讲解 0、单题课 0、少于六题课 0。题目及故事题共 20,804 道通过实际判分检查,音频与 Docker 验证通过;教师签审仍为独立待办。详见 本版审计及验证记录。


🚀 快速开始

Docker 全新部署与旧版升级

只需 Git 和 Docker Desktop(Windows/macOS)或 Docker Engine + Compose(Linux),无需在本机安装 Node.js、Python、FFmpeg,也无需 AI API Key。建议预留至少100 GB磁盘空间,容纳镜像、构建缓存和资源暂存。

全新部署:

git clone --branch main https://github.com/wuwangzhang1216/ChinaTextbookStudyFree.git
cd ChinaTextbookStudyFree
docker compose build --build-arg ASSETS_RELEASE=v1.8.3
docker compose up -d --no-build --wait --wait-timeout 120

打开 http://localhost:8080。首次构建自动下载、校验 v1.8.3 全部资源,复用已验证的 MP3 与转换缓存,再构建网站。

从旧版升级:升级前备份自定义代码,在原项目根目录执行以下命令,并保留原来的 .env、Compose 项目名和访问协议、域名/IP、端口;如原先使用 -p、-f 等参数,以下每条 docker compose 命令都沿用这些参数。构建完成后再替换容器,浏览器学习记录继续保存在同一地址下。

git switch main
git pull --ff-only origin main
docker compose build --build-arg ASSETS_RELEASE=v1.8.3
docker compose up -d --no-build --force-recreate --wait --wait-timeout 120

确认服务健康:以下命令应显示容器 healthy,并输出 ok;wget 在容器内运行。

docker compose ps
docker compose exec -T web wget -q -O - http://127.0.0.1:8080/healthz

重新加载原页面后,可打开中文数学讲解点击“朗读讲解”,以及中文课文点击“朗读第 5 句”,确认播放正常。自定义端口时使用原地址。

Docker 验证(v1.4.3)已通过:在 Apple Silicon/ARM64 上验证完整材料包全新构建,以及从 v1.4.0-content、v1.4.2-edge-audio 两种旧容器按原项目、原端口升级。三个运行容器均通过题库保留、全量音频 SHA-256、媒体引用、HTTP 与 Range 206 检查;中文讲解自然播完并解锁下一步,升级保留浏览器学习目标。命令与验收范围见 Docker 安装说明。未在本轮验证 x86 主机或实体手机/iPad。

其他启动方式

安卓自行安装:用 Android Studio 打开 apps/android,或从 GitHub Actions 下载构建成功的调试 APK。当前是加载 HTTPS 课堂的在线客户端;构建步骤、录音权限和已知限制见 安卓工程说明。

1. 克隆仓库

以下步骤启动当前线上版本。需要 Node.js 20+、Python 3.9+,以及带 libmp3lame 的 FFmpeg;请将 Python 和 FFmpeg 加入系统 PATH。

git clone --branch main https://github.com/wuwangzhang1216/ChinaTextbookStudyFree.git
cd ChinaTextbookStudyFree

2. 下载或升级完整资源

音频、图片和配套数据通过 v1.8.3 Release 分发。音频按体积分为多个独立 ZIP,每个不超过 1.4 GB;新版安装器先逐文件校验已有资源,仅下载需要更新的分包,解压后再次核验,已有目录也会正常更新。

# macOS / Linux:在仓库根目录执行
python3 scripts/install-release.py --tag v1.8.3

# Windows PowerShell
py -3 scripts/install-release.py --tag v1.8.3

完整包包含 MP3、原路径音频、数据、配图和课本原页,以及可选的匹配源码与现成网站。manifest.json、files.jsonl 和 SHA256SUMS 提供附件及逐文件校验。仓库中的新版安装器默认按分包增量更新:本地文件与目标版本完全一致的包不再下载,--dry-run 可预览所需包及大小。首次完整安装建议预留至少 80 GB 用于下载、暂存和安装,已有备份另计;有本地修改时先备份。增量更新、单独资源下载、离线安装及验证命令见 安装与升级说明。

3. 运行 Web 端

npm ci
npm run dev

访问 http://localhost:3000。构建复用包内音频和已验证的转换缓存,无需调用在线 TTS。生产构建执行 npm run build,输出到 apps/web/out/;类型检查使用 npm run type-check。

直接使用现成网站:无需 Git、Node.js 或 FFmpeg。从 Release 下载新版 install-release.py,执行:

python3 install-release.py --tag v1.8.3 --mode static --root ChinaStudyFree-site
python3 -m http.server 8080 --directory ChinaStudyFree-site

打开 http://localhost:8080。升级现有静态站点时,将 --root 指向原站点目录;页面、数据和音频一起更新。正式托管使用支持 HTTP Range 的静态服务器,并在发布后刷新 CDN 缓存。

电脑、手机与部署

电脑使用侧栏和宽屏阅读布局,手机使用底部导航和单列阅读。此前线上版本已检查 23 类页面 × 7 种尺寸(320×568 至 1920×1080),并测试完整答题、阅读、刷新恢复、错题、商店和家长时间限制。2026-10-05 的 main 更新另通过 45 项线上 HTTP 检查、完整文件与媒体引用核对,并验证 320、390 和 1440 像素宽度的课程讲解播放与边框进度。手机尺寸模拟不等于真机验收:真实 iPhone/Android、抖音内置浏览器的播放和麦克风权限仍需复核。详见 Web 深测报告。

线上使用东京区域的私有 S3 + CloudFront HTTPS,使用 AWS 提供的链接;没有 EC2/Lightsail、数据库或业务后端。按存储、请求和流量计费,没有 $7.50/月的服务器固定费用。部署步骤见 AWS Web 部署说明。

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 端特点:

统一设计系统(DesignSystem/)

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

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

学习体验

装扮系统(earn → spend → express 闭环)

留存机制

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

5. (可选)运行数据生成 Pipeline

本次新增26册的版次、目录、来源与审校范围见五四制核对报告;原题库恢复的历史记录见旧版审计。语文课外阅读的历史难度校准与修订流程见 内容质量审计与升级说明。

中文补音当前使用 Edge TTS,默认并发 4、每秒最多启动 2 次合成(含重试),失败按指数退避。下面的生成命令只用于修改内容后的重新生成;安装和构建现成 Release 不需要调用在线 TTS。改写内容应先完成样例审阅,再同步文本、配图、音频,并保留原数据备份。

如需从教材 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

# 为修改后的中文内容补音(需联网;安装 Release 时无需执行)
pip install 'edge-tts>=7.0'
python scripts/tts/collect_texts.py
python scripts/tts/edge_tts_batch.py --language Chinese --workers 4 --requests-per-second 2

# 构建前端数据
npm run build:data --workspace=china-study-free

🏗️ 项目结构

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 批量合成
│   ├── install-release.py          # 校验并安装/升级 Release 资源(线上版本分支)
│   ├── download-assets.sh          # 旧版资源下载器(Linux/macOS)
│   ├── download-assets.ps1         # 旧版资源下载器(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/    #   单元测试(域逻辑 + 每日任务)
    │   └── ChinaTextbookStudyUITests/  #   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。

内容说明:

  1. 资源包包含教材知识大纲、课文文本及课本原页;教材文本与图片的版权属于各自权利人
  2. 单元练习和课外故事由 AI 生成并持续修订,生成内容仍需教师审核
  3. 项目的 MIT 代码许可不代表授予第三方教材内容的使用权
  4. 如相关版权方认为本项目存在任何问题,请与我们联系,我们会第一时间响应处理

🤝 如何参与

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


🛣️ 路线图

路线图包含历史已完成项,当前版本和资源规模见上方安装与升级说明。完整材料包支持下载后离线安装;Docker 首次构建需联网下载资源。校园内网的跟读录音需要 HTTPS;全库 PWA 离线预缓存及实体手机 / iPad 验收仍需补充。


📜 许可协议

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

Copyright (c) 2026 wangzhang wu


💌 写在最后

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

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

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

congcong-school (wuwangzhang1216/congcong-school)

正在搜索数据库…

这是什么?这是一个免费、开源、非商业的学习平台,涵盖中国小学全部课程(1–6年级)的语文、数学、英语和科学,目的是让各地的孩子都能获得同等质量的学习资料。
这是网站还是原生应用?两者都有:它以静态网页应用的形式发布(无需 Node.js 后端,通过 CDN 部署),同时还有独立的原生 SwiftUI iOS 应用;也可以通过 Android Studio 从 apps/android 构建 Android 调试版 APK。
怎样让它运行起来?克隆仓库,然后运行 'docker compose up -d --build' 即可一条命令完成部署,并自动下载所有内容;或者从 GitHub Releases 手动获取五个资源包(约 2.06GB)并启动网页应用;iOS 应用则通过 XcodeGen 在 Xcode 中打开。
手动运行需要预先安装什么?网页应用需要 Node.js 20+、Python 3.9+,以及编译了 libmp3lame 的 FFmpeg(三者都需在 PATH 中);iOS 应用需要 macOS、Xcode 16+ 和 XcodeGen。
我的学习进度能在多台设备之间同步吗?不能。学习进度、正确率和阅读星星仅保存在当前浏览器的本地存储中,目前没有云端账户,也不支持跨设备同步(仍在路线图中)。
MIT 许可证实际涵盖哪些内容?MIT 许可证只涵盖项目的代码;教材大纲、课文和页面图片仍归其原版权所有者所有,而 AI 生成的题目和故事仍需教师持续审核。
聪聪是什么?聪聪是平台的熊猫吉祥物,在 iOS 上使用 SwiftUI Canvas 原生绘制,具有呼吸、眨眼和情绪反应等动画。孩子们可以用学习中获得的宝石为它解锁服装、配色主题和课程背景。
练习题是怎么制作的?单元测验和知识点讲解由 AI 根据官方教材结构生成,并由教师持续审核。内部审计发现,仍有 1,498 节课缺少讲解,1,183 节课只有一道题。
可以离线使用吗?网页应用需要网络连接才能加载资源,但 iOS 应用内置了一本离线示例教材(一年级数学第一课,附带 TTS 语音),无需联网即可体验完整流程。
它涵盖哪些学科和年级?数学和科学覆盖 1–6 年级;语文覆盖 1–6 年级(另加 188 篇分级故事);英语覆盖 3–6 年级(另加 96 篇分级故事)。内容依据 PEP 等官方教材版本以及统一的中国课程标准编写。
大小
70.8 MB
星标
1.4K
时长
7个月
提交 · 90 天