# learn

**Repository Path**: ai_yu666/learn

## Basic Information

- **Project Name**: learn
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 五年级学习工作台 · 学科闯关版

一个面向 **五年级（10–11 岁）学生** 的纯前端交互式学习网页应用。以「学科闯关 + 每日习惯 + 星星激励 + 萌宠陪伴 + AI 小老师」为核心，数据存本机浏览器，可一键连云端实现多设备同步，并内置家长管理模式。

> 在线地址（CloudStudio 部署）：https://55dead90c97a48f98460451f0e989746.app.workbuddy.link

---

## 一、功能特性

| 模块 | 说明 |
| --- | --- |
| 📚 学科闯关 | 语文 / 数学 / 英语 / 科学 / 奥数 五科；语数英科已**对齐五年级上册真实课纲**（语文8 / 数学8 / 英语6 / 科学5 单元），每单元含课文/习作主题 + 可一键「🤖 AI 出题」。 |
| 🧩 奥数 | **11 讲**同步人教版五年级上册（速算巧算/找规律/周期/数字谜/鸡兔同笼/行程/植树与间隔/图形面积/应用题综合/逻辑推理/趣味挑战），每讲 8 题、选择/判断/填空/步骤排序混合；**不提供提示**（先独立思考），每题可点「🤖 AI 老师讲思路」获得引导式讲解（不给答案）。 |
| 🎮 练习引擎 | 选择题、判断题、填空题、排序题 / 连词成句、翻翻卡、配对游戏、阅读读后答题七种形式；提示默认隐藏，先思考再点「看提示」。 |
| 🧮 数学自动出题 | 计算 / 方程 / 应用题 / 几何 四类**动态生成器**，数值真随机、难度随等级缩放。 |
| 🤖 AI 小老师 | 错题讲解（含类似巩固题）、按难度无限出题、自适应难度、**多题型出题（选择/判断/填空/排序，严格校验坏题丢弃）**、奥数「讲思路」模式；直连 Agnes-AI。 |
| ⭐ 星星 & 🏅 徽章 | 22 个徽章里程碑；星星可在「奖励乐园」兑换；萌宠在得星/解锁时庆祝。 |
| 🐱 萌宠养成 | Petdex 大橘猫桌宠，可**拖动**；含**亲密度 / 等级 / 猫粮**系统：完成练习与每日任务得猫粮（每日封顶 8），可**喂猫粮 / 摸摸头 / 玩耍**提升亲密度，每满 100 升 1 级，互动时播放随机**喵叫声**（Web Audio 合成）；浮窗点击即互动。 |
| 📗 课本练一练 | 语 / 数 / 英 / 科 各新增「课本练一练」主题，混编书本练习风格的多题型题目。 |
| ⏰ 作息 / 🌱 习惯 / 🎯 目标 / 📚 阅读 / 🎁 奖励 | 完整成长管理闭环，每日自动清零。 |
| 👨‍👩‍👧 家长模式 | PIN（SHA-256 + 盐）进入；**可编辑**作息 / 习惯 / 奖励 / 每日任务；可改星星说明、萌宠；含 **学习周报**、**星星流水账（可手动调星）**、**连胜保护券**。 |
| 📈 成长档案 | 各科正确率雷达图 + 月度星星趋势 + 里程碑时间线，**一键导出 PNG**。 |
| 🎉 庆祝 & 📱 PWA | 通关 / 升级 / 连胜里程碑全屏庆祝 + 音效（可关）；支持「添加到主屏幕」离线可用。 |
| 👧 多娃切换 | 一个孩子一份独立存档与云端数据（学生ID 不同即独立）。 |
| ☁️ 云端同步 | Supabase 多设备实时同步（凭据在「☁️ 同步」中填写，打开即连）。 |

---

## 二、目录结构

```
study-workbench/
├── index.html        # 页面结构 + 各类弹窗（星星说明 / 家长设置 / 同步 / AI / PIN / 编辑管理）
├── styles.css        # 儿童明亮主题样式
├── data.js           # 五年级内容：5 学科、25 主题、12 每日任务、22 徽章、默认说明文案
├── app.js            # 全部应用逻辑（状态、练习引擎、萌宠、同步、AI、家长编辑、周报 / 档案 / 多娃 / PWA）
├── schema.sql        # Supabase 建表 + RLS + Realtime 脚本
├── manifest.webmanifest  # PWA 清单
├── sw.js             # Service Worker（静态资源 cache-first，云端请求 network-first）
├── assets/
│   ├── big-orange-cat.webp   # 萌宠精灵图（1536×1872，192×208/帧，9 行动画）
│   ├── icon-192.svg / icon-512.svg  # PWA 图标
└── supabase/
    ├── config.toml
    └── functions/ai-tutor/index.ts   # （可选）Supabase Edge Function AI 代理
```

---

## 三、本地运行

纯静态站点，无需构建。任选其一：

```bash
# 方式 A：直接用浏览器打开
open index.html

# 方式 B：起一个本地静态服务器
python3 -m http.server 8080   # 然后访问 http://localhost:8080
```

> 说明：本地直接双击 `index.html` 也能用；但「云端同步」与「AI 小老师」建议通过 http 服务器访问，避免个别浏览器对 `file://` 的限制。

---

## 四、部署

项目已部署在 CloudStudio 沙箱，链接见顶部。**重新部署**：将 `study-workbench/` 目录（含 `index.html`）作为静态站点目录上传，入口 `index.html`、端口 `3000` 即可。

---

## 五、云端同步（Supabase）

1. 到 Supabase 新建免费项目，复制 **Project URL** 与 **anon public key**。
2. 在 SQL Editor 运行 `schema.sql`（建表 `study_state` + 开放 RLS + 开启 Realtime）。
3. 应用内点右上角「☁️ 未连接云端」→ 粘贴 URL / key / 学生ID → 保存并连接。
   - 凭据需**自行填写**（数据最小化，不预填）；填写后打开即自动连接。
   - 家里多个孩子：把「学生ID」改成不同名字（如 `xiaoming` / `xiaohua`）各自独立。
4. 连接后，任意设备的修改会通过 Realtime 实时同步到其他设备。

> ⚠️ 安全提示：预填的是 Supabase **anon key**（可公开），意味着拿到分享链接者都能读写同一项目的云端数据。若要更私密，请在 Supabase 后台改用带行级安全策略的密钥，或自行部署 Edge Function 代理。

---

## 六、AI 小老师（Agnes-AI）

- 直连 **Agnes-AI 国内站** `https://api.agnes-ai.cn/v1`，模型 **`agnes-2.5-flash`**。
- ⚠️ **密钥收敛**：前端**不再预填默认 Key**，请在本机「🤖 AI」设置中自行填写你的 Agnes Key（仅存本机浏览器 `localStorage`，不上传服务器）。
- 点错题后的「🤖 问问 AI 为什么错」可获温和讲解 + 一道巩固题；主题页「🤖 AI 出 5 题」可按当前难度出新鲜题；家长端「📊 学习周报」可让 AI 生成本周薄弱点小结。
- 更安全方案：部署 `supabase/functions/ai-tutor`（密钥在服务端 Secrets），前端会优先走该代理。`index.ts` 默认也指向 Agnes-AI（可用 Secrets 覆盖 `OPENAI_BASE_URL` / `OPENAI_MODEL` / `OPENAI_API_KEY`）。

---

## 七、家长模式

- 点「👨‍👩‍👧 家长」输入 PIN 进入。
  - **密码安全化**：PIN 以 **SHA-256 + 随机盐** 哈希存储（不再存明文）；连续错误 5 次锁定 5 分钟；忘记密码可通过安全问题（若已设置）或家庭设备降级重设。
  - **首次进入**使用兼容默认密码 `1qaz!QAZ`，会提示尽快在「⚙️ 家长设置 → 🔐 修改家长密码」改掉。
- 进入后可：
  - 查看孩子星星、连续打卡、闯关与徽章进展（实时同步）；
  - **📊 学习周报**：本周 / 上周打卡天数、任务完成率、获得星星、各科练习量与正确率，并可让 AI 生成薄弱点小结；
  - **⭐ 星星流水账**：查看每笔星星来龙去脉，家长可手动 ±1 / ±5 调星；
  - **🛡️ 连胜保护券**：在「🎁 奖励乐园」用 5⭐ 购买，断签当天自动消耗 1 张保住连胜（最多持 2 张）；
  - 点「⚙️ 家长设置」改星星说明文案、萌宠开关与名字、**音效开关**、改家长密码、切换 / 添加孩子；
  - 点「✏️ 编辑作息 / 编辑习惯 / 编辑奖励 / 编辑每日任务」增删改对应内容（仅家长可见，孩子端不显示编辑按钮）。
  - 在「⚙️ 家长设置」底部可 **📤 导出备份 / 📥 导入备份** 整份学习数据（JSON 文件），避免清缓存导致数据丢失。

---

## 八、二次开发 / 自定义

所有内容集中在 `data.js`，无需改动 `app.js`：

- **科目**：`SUBJECTS`（id / 标题 / 副标题 / 颜色）。
- **主题练习**：`TOPICS`（科目、类型 quiz/flashcard/match/reading、内容或 `generator` 名）。
- **数学出题**：`GENERATORS`（见 `app.js`，`lv` 控制难度 1–5）。
- **每日任务**：`DAILY_TASKS` 仅作为首次启动的迁移数据源；运行时任务存于 `store.taskDefs`，家长可在「✏️ 编辑每日任务」里增删改（图标 / 名称 / 科目 / 星星数 / 频次）。
- **徽章**：`BADGES`（图标 / 名称 / 解锁条件 `cond(store)`），当前 22 个。
- **作息 / 习惯 / 奖励**：运行时存于 `store.routineDef` / `store.habitDefs` / `store.rewards`，默认值见 `app.js` 的 `ROUTINE_DEF_DEFAULT` / `HABIT_DEFS_DEFAULT`，家长可在界面内编辑。
- **萌宠**：替换 `assets/` 下的精灵图并调整 `app.js` 中 `PET_FW` / `PET_FH` / `PET_ROWS` 即可换宠。

---

## 九、技术架构

- 纯前端单页应用，无后端依赖；`localStorage` 为本地数据源，`save()` 触发云端防抖同步。
- 状态：`store`（默认 `defaultState()`），`load()` 负责迁移默认值与每日清零。
- 同步：Supabase JS（`upsert` + Realtime 订阅），`syncCfg` 由用户在「☁️ 同步」中填写后自动连接。
- AI：`callAI()` 优先 Supabase Edge Function，失败回退浏览器直连 Agnes-AI（儿童安全系统提示词 + 严格 JSON 输出）。

---

## 十、教材同步（五年级上册）

语数英科四科主题已对齐**五年级上册真实教材课纲**，孩子打开就知道「这周学校学到哪了」：

| 学科 | 教材 | 单元数 | 示例单元 |
| --- | --- | --- | --- |
| 📖 语文 | 部编版·人教版 | 8 | 一花一鸟总关情 / 阅读要有速度 / 民间故事 / 家国情怀 / 说明文 / 舐犊之情 / 四时景物 / 读书明智 |
| 🔢 数学 | 人教版 | 8 | 小数乘法 / 位置 / 小数除法 / 可能性 / 简易方程 / 多边形面积 / 植树问题 / 总复习 |
| 🔤 英语 | PEP（三年级起点） | 6 | What's he like? / My week / What would you like? / What can you do? / There is a big bed / In a nature park |
| 🔬 科学 | 人教鄂教版 | 5 | 烧水过程中的热传递 / 后代与亲代 / 显微镜下的生物世界 / 光 / 太阳能热水器 |

- 每个单元主题进入后是**离线可用**的练习题（课文/考点事实题），含选择、判断、填空、排序等多种题型；数学单元还复用动态出题生成器。
- 每科末尾附「课本练一练」主题，混编课本练习风格的多题型题目。
- 点「🤖 AI 出 5 题」可让 Agnes 按**该单元考点**生成原创练习题（习作/口语交际/语法点都写进提示词）。
- ⚠️ 版权：仅取「单元/课文标题 + 习作主题」等**事实性结构**，不收录课文正文；AI 出题亦为原创练习。
- 📚 教材 PDF（语数英科五上/五下，版权教材不入代码仓库）网盘共享：
  **夸克网盘：https://pan.quark.cn/s/1c096e3e114c**（家长/孩子自行下载查阅；如需随仓库分发请自行替换链接）。

## 十一、常见问题

- **云端连不上？** 检查 URL/key 是否正确、项目是否建表；或先忽略云端，本地模式照常使用。
- **AI 没反应？** 检查「🤖 AI」设置里 key 是否就绪；网络或额度异常时会有友好提示并退回原题。
- **数据在哪？** 默认存本机浏览器；连云端后多设备共享同一 `student_id` 的数据。
- **萌宠不动 / 比例怪？** 确认 `assets/big-orange-cat.webp` 存在；精灵图尺寸须与 `PET_FW×PET_FH` 及 `background-size` 一致（当前 192×208 / 1536×1872）。