为小学到高中学生打造的互动课件学习乐园
An interactive courseware playground for K12 students

🚀 GitHub Pages · 🌏 Cloudflare Pages

• 纯静态网站 — 无后端、无框架运行时,GitHub Pages 与 Cloudflare Pages 双渠道托管
• PWA 全屏壳 — 可"添加到主屏幕",平板/手机以全屏应用形态运行,无浏览器界面干扰
• 课件离线可玩 — Service Worker 渐进缓存:主站壳预缓存,玩过的课件自动进缓存(cache-on-visit),断网可重玩;主站卡片显示「可离线」角标
• 左右分栏主界面 — 学段选择(小学 / 初中 / 高中)+ 年级过滤 + 学科分类(数学 / 物理 / 化学 / 编程 / 科学 / 逻辑,小学自动隐藏物理化学)
• 课件完全独立 — 每个课件一个目录,自带 HTML/CSS/JS,互不依赖
• 中英双语 — 主站与全部课件共享语言偏好(localStorage: kidslab.lang)
• 深浅主题 + 4 种强调色 — 跟随系统,可手动切换
• 搜索过滤 — 标题 / 描述 / 标签双语实时搜索(按 / 聚焦)
• 侧栏收拢 — 桌面端窄轨模式,移动端抽屉
• 置顶课件 — Three.js 3D 欢迎页锁定第一位

kidslab/
├── index.html              # 主站入口
├── manifest.webmanifest    # PWA manifest(全屏壳 + 图标)
├── sw.js                   # Service Worker(构建产物,由 build 生成,勿手改)
├── assets/                 # 主站样式/脚本/字体/logo/PWA 图标
├── src/                    # 课件源码(开发目录)
│   └── <courseware-id>/
│       ├── course.json     # 课件元数据(必需)
│       ├── index.html      # 课件入口(必需)
│       └── *.css / *.js    # 课件资源
├── courseware/             # 构建产物(minify 后) + index.json 清单
├── scripts/
│   ├── build.mjs           # 构建:校验 + 压缩 + 生成清单与 sw.js
│   ├── sw.js               # Service Worker 源码模板
│   ├── icons.mjs           # PWA 图标生成(logo 变更后 npm run icons)
│   └── serve.mjs           # 本地预览服务器
└── .github/workflows/deploy.yml   # 推送 main 自动发布 GitHub Pages + Cloudflare Pages

1. 在 src/ 下新建目录,如 src/my-lesson/
2. 编写 index.html + 样式脚本(只用相对路径,不依赖其他课件)
3. 添加 course.json:

{
  "id": "my-lesson",
  "title":       { "zh": "我的课件", "en": "My Lesson" },
  "description": { "zh": "一句话介绍", "en": "One-line intro" },
  "category": "math",
  "levels": ["primary", "junior"],
  "grades": ["g4", "g5"],
  "tags": ["分数", "小数"],
  "icon": "🎓",
  "order": 80
}

1. 构建并预览:

npm ci
npm run build     # src/ → courseware/(js/css 压缩 + 校验 + 生成 index.json)
npm run preview   # http://localhost:8080

1. 提交推送,workflow 自动重新构建并发布。

推送到 main 即触发 .github/workflows/deploy.yml:npm ci → npm run build → smoke 测试 → 按仓库变量重新构建发布产物 → 组装同一份 _site/(含 manifest.webmanifest 与 sw.js)→ 同步发布到 GitHub Pages 与 Cloudflare Pages。

Cloudflare Pages 一次性配置：

# 1. 在 Cloudflare 创建 Pages 项目，项目名 kidslab-app（"kidslab" 已被他人占用），Production branch 设为 main
# 2. 配置 Cloudflare Pages 专用 API token；token 需具备 Account → Cloudflare Pages → Edit
gh secret set CLOUDFLARE_PAGES_API_TOKEN
# 3.（Cloudflare 账号下有多个 account 时才需要）
gh secret set CLOUDFLARE_ACCOUNT_ID

cloudflare/analytics/ Worker 可继续使用 CLOUDFLARE_API_TOKEN；Pages 发布优先读取 CLOUDFLARE_PAGES_API_TOKEN，避免把 Worker token 扩权。

自定义域名绑定：

1. 在 Cloudflare Pages 项目 kidslab-app 的 Custom domains 添加 kidslab.talkincode.net。
2. 确认 talkincode.net DNS 里存在记录：kidslab CNAME kidslab-app.pages.dev（注意不是 kidslab.pages.dev，那是他人的同名项目）。如果域名与 Pages 项目在同一 Cloudflare 账号，Cloudflare 通常会自动创建；否则需要按 Custom domains 页面提示手动添加。
3. 等待 Custom domains 状态变为 Active，再用 dig kidslab.talkincode.net CNAME 和 curl -I https://kidslab.talkincode.net/ 验证。

国内访问稳定性必须以实测为准。未完成多地区/多运营商验证前，不把任何入口表述为“国内稳定访问”。

• 主站与课件可"添加到主屏幕",以全屏(fullscreen)应用形态运行
• 缓存策略:主站壳(index.html + assets)按内容 hash 预缓存,发版自动失效;课件 network-first + cache-on-visit —— 在线永远拿最新,玩过的断网可重玩
• SW 更新保守:新版本等所有页面关闭后接管,不打断正在玩的孩子
• 本地验证:npm run build && npm run preview,访问后停掉服务器,已访问页面仍可打开

首次启用:仓库 Settings → Pages → Source 选择 GitHub Actions。

新课件请从 docs/courseware-template/ 双语/主题模板起步;课件规划清单见 docs/courseware-plan/。

• 小学课件计划的已完成/未实现状态集中维护在 docs/courseware-plan/status.md。
• 每次完成规划课件后,必须同步更新状态清单、必要的学科规划文档和本 README 的内置课件列表;Agent 规约见 AGENT.md。
• 当前最低自动校验是 npm run build;更完整的交互验收缺口记录在状态清单的验收矩阵中。

双许可结构：

• 代码（构建脚本、主站框架、课件程序逻辑）：MIT
• 课件内容（教学设计、文案、图形等创作素材）：CC BY 4.0 — 自由使用与传播，惟须署名

Code is MIT licensed. Courseware content (lesson designs, copy, artwork) is licensed under CC BY 4.0 — free to use and share with attribution.