用 WorkBuddy 给孩子做一个打字指法启蒙工作台

docs/cases/submissions/typing-kids-hero/index.md

@@ -0,0 +1,280 @@
+---
+title: 用 WorkBuddy 给孩子做一个打字指法启蒙工作台
+summary: 从一句需求出发，生成单文件 HTML 打字启蒙台：指法卡片、拼音/英语/句子练习、每日目标、闯关积分、扭蛋奖励与莫扎特背景音乐，并部署为在线链接
+author: TODD-9527
+date: "2026-08-21"
+category: 创意开发
+difficulty: 中等
+aside: false
+outline: false
+skills:
+  - 资料库（在线部署）
+  - AI 生图（ImageGen）
+  - 图像处理（PIL）
+  - 音频转码（imageio-ffmpeg）
+  - HTML 单页应用生成
+tags:
+  - 儿童教育
+  - 打字指法
+  - HTML
+  - 本地存储
+  - SVG
+  - 游戏化学习
+  - 拼音
+  - KET
+  - 背景音乐
+  - 公有领域录音
+---
+
+# 用 WorkBuddy 给孩子做一个打字指法启蒙工作台
+
+## 场景描述
+
+家里 8 岁的孩子（二年级）开始接触电脑打字。市面上的打字练习软件要么广告多、要么枯燥，孩子练两天就没了兴趣。作为家长，我希望有一个**孩子愿意天天打开**的打字启蒙工具：
+
+- 能教规范指法（哪根手指按哪个键），而不只是「对着屏幕盲打」
+- 内容贴合二年级：语文拼音 + KET 初级英语，最好还能整句拼读
+- 有每日目标和奖励机制，让孩子养成「每天练一点」的习惯
+- 单文件、无广告、零外链，手机和电脑都能用
+- 练习时能放点莫扎特舒缓背景音乐，营造专注氛围
+
+如果手写这个工具，光是虚拟键盘的指法高亮、进度环、闯关系统、扭蛋抽奖就要写几百行前端代码，更不要说集成版权安全的古典音乐。所以我把它交给 WorkBuddy：先描述需求，让它生成第一版，再按孩子的使用反馈逐步迭代。
+
+## 想要完成的任务
+
+- **输入**：一句自然语言需求 + 多轮迭代反馈（加难度、加句子、加奖励、加图标、加背景音乐）
+- **目标**：一个单文件 HTML 打字启蒙工作台（全内联、零外链、离线可用、含公有领域背景音乐）
+- **交付物**：
+  - 可在浏览器直接使用的单文件 HTML（约 3.2MB，含内嵌音乐与图标）
+  - 部署到资料库后的公开在线链接
+  - 配套的吉祥物图标（PNG / ICO / favicon）
+
+## 前置条件
+
+- WorkBuddy 版本：支持本地文件读写与资料库在线部署的版本
+- 操作系统：Windows（macOS / Linux 同样适用）
+- 所需输入：无需外部素材，全部由 WorkBuddy 内置能力生成
+- 可选：资料库连接授权（用于生成在线分享链接）
+
+## 使用的 Skill
+
+| 能力 | 用途 | 来源 |
+| --- | --- | --- |
+| HTML 单页应用生成 | 生成工作台本体（全内联 CSS/JS、localStorage 存储） | WorkBuddy 内置 |
+| 资料库（library） | `import_html.py` 上传 + `publish_page.py` 发布公开链接 | WorkBuddy 内置 |
+| AI 生图（ImageGen） | 生成「小侠客敲键盘」吉祥物主图 | WorkBuddy 内置 |
+| 图像处理（PIL） | 去水印、裁切、生成多尺寸 PNG 与多分辨率 ICO | Python 库 |
+| 音频转码（imageio-ffmpeg） | OGG/WAV → MP3、截取片段、降码率 64kbps | Python 库 |
+| SVG 矢量绘制 | 虚拟键盘、扭蛋贴纸、奖杯墙、音符图标等全部图标 | 手写内联 |
+| 公有领域录音获取 | Wikimedia Commons API 检索莫扎特钢琴协奏曲录音 | 外部 API |
+
+## 在 WorkBuddy 中的操作
+
+### 第一步：描述需求，生成第一版
+
+把需求发给 WorkBuddy：
+
+```text
+帮8岁孩子做一个打字练习启蒙工作台，练习规范指法，每天打50个字，
+有卡片、组词练习和闯关积分奖励。
+```
+
+WorkBuddy 先确认了两个关键变量（词库类型、每日目标数），随后生成第一版单文件 `typing-kids.html`，包含：
+
+- 今日目标进度环（每天 50 个正确字）+ 连续练习天数，达标放烟花
+- 指法卡片：整键盘按左右手/手指分色，点任意键显示「用哪根手指按」，基准键 ASDF JKL; 高亮
+- 组词练习：虚拟键盘实时高亮正确手指，错字提示重按
+- 闯关积分：累计正确字数升级（手指小兵 → 键盘大侠 → 打字宗师）+ 奖杯墙
+- 家长设置（4 位密码）：改目标、增删词库、重置进度、导出/导入备份
+
+### 第二步：按孩子情况迭代升级
+
+孩子已上二年级，第一版词库偏简单。我连续提了几轮反馈：
+
+**第 1 轮（加难度）**：
+
+```text
+加大一些难度，孩子2年级了，可以参考语文二年级内容和ket初级内容
+```
+
+词库升级为双轨 52 词：语文拼音词（太阳、朋友、老师、学校…，屏幕显汉字 + 拼音注音）+ KET 初级英语（school、teacher、pencil、colour…）。练习界面加「语文/英语」标签，每轮随机打乱词序。词库结构改为 `{typ, disp, g}` 对象，支持「拼音|汉字」格式，旧数据自动迁移兼容。
+
+**第 2 轮（加句子模式）**：
+
+```text
+加「句子/短文」模式（如「我爱北京天安门」整句拼读），把二年级难度再拉高一档
+```
+
+新增句子朗读模式：内置 20 句（语文短句 + KET 简单句），整句逐字母高亮正确手指，整句无错额外 +5 分。今日卡片顶部加「词语闯关 / 句子朗读」切换。
+
+**第 3 轮（加奖励功能）**：
+
+```text
+增加奖励功能
+```
+
+新增「扭蛋乐园」标签页：用积分扭蛋抽 10 个 SVG 虚拟收藏（普通/稀有/史诗三档），重复抽到返还 +10 分，收藏册记「已集 X/10」，集齐庆祝。家长设置可调扭蛋消耗（10–200 分）。
+
+**第 4 轮（加图标）**：
+
+```text
+帮我做一个合适的图片作为图标，符合小小打字侠这个名字的。
+```
+
+用 ImageGen 生成卡通小侠客吉祥物（戴星头盔、红披风、敲彩色键盘），PIL 裁切去水印后生成 `icon-1024.png`、`favicon-32.png`、`apple-touch-icon.png`、多分辨率 `icon.ico`，base64 内嵌进 HTML，桌面快捷方式指向本地 ICO。
+
+**第 5 轮（加背景音乐）**：
+
+```text
+增加背景音乐，选几曲莫扎特的no。22的曲子
+```
+
+按用户指定的「莫扎特第22号钢琴协奏曲 K.482」找公有领域录音：
+
+1. IMSLP 上的 K.482 完整录音是「欧盟公有领域 / 美国非公有领域」，公开链接有版权风险，弃用；
+2. archive.org 被墙不可达；
+3. 改从 Wikimedia Commons 检索，K.482 完整乐章只有开头小样，补充三首同期舒缓乐章凑成「几曲」。
+
+最终内嵌 4 首（均 Public Domain）：
+- K.482 第22协奏曲 开场片段（约30秒，正主）
+- K.503 第25协奏曲 第二乐章 行板（90秒）
+- K.466 第20协奏曲 第二乐章 浪漫曲（90秒）
+- K.595 第27协奏曲 第二乐章 小广板（90秒）
+
+转码用 imageio-ffmpeg（系统无 ffmpeg，用阿里云镜像 pip 安装 31MB wheel），OGG/WAV → 64kbps MP3（Safari 全兼容），乐章各截 90 秒，共 2.3MB，base64 内嵌进 HTML。加音乐按钮（音符图标，点击 toggle，ended 自动循环下一首，音量 0.35，localStorage 记偏好）。
+
+随后按用户要求「音乐默认打开」，把默认偏好 `on` 改为 `true`，加 `tryAutoplay()` 处理浏览器自动播放策略：页面加载尝试播放，被拦截则监听首次点击/按键/触摸后自动播放。
+
+### 第三步：部署为在线链接
+
+```text
+重试在线部署
+```
+
+通过资料库上传 HTML 并发布公开链接。踩坑记录：覆盖已有页面必须用 `--node-block-id` 参数（误用 `--node-id` 会报「文件不存在」），发布后用 curl 验证链接可达（302 → 发布页）。每次迭代更新都用此覆盖流程。
+
+### 提示词或任务指令
+
+以下是可以复用的核心需求描述：
+
+```text
+帮8岁孩子做一个打字练习启蒙工作台，练习规范指法，每天打50个字，
+有卡片、组词练习和闯关积分奖励。
+要求：
+- 单文件 HTML，全内联、零外链、离线可用
+- 手机/电脑自适应，按钮 ≥ 50px，亮色活泼
+- SVG 图标，不用 emoji
+- 数据存 localStorage，家长设置可导出/导入备份
+```
+
+## 在 WorkBuddy 中的效果
+
+最终交付物：
+
+- **主文件**：`typing-kids.html`（单文件，约 3.2MB，全内联 HTML + CSS + JS + 4 首音乐 + 图标 base64）
+- **在线链接**：https://workbuddy.link/p/rdtw8VpIsyRdVyrRHAgT9G
+- **图标文件**：`icon-1024.png`（1.3MB 高清原图）、`icon.ico`（16–256 多分辨率）、`favicon-32.png`、`apple-touch-icon.png`
+- **音乐文件**：`k482.mp3`、`no20.mp3`、`no25.mp3`、`no27.mp3`（原始 ogg/wav 留档）
+- **桌面快捷方式**：`小小打字侠.url`（指向在线链接与本地 ICO）
+
+![小侠客吉祥物图标](./assets/mascot-icon.png)
+
+*ImageGen 生成的卡通小侠客吉祥物：戴星星头盔、披红色小披风，正在敲彩色键盘。*
+
+功能效果概述：
+
+- 今日首页：词语/句子模式切换 + 每日 50 字进度环 + 连续天数，达标放烟花
+- 指法卡片：整键盘按左右手/手指分色，点键显示对应手指，基准键高亮
+- 词语练习：拼音+英语 52 词，屏幕显汉字 + 拼音注音，虚拟键盘实时高亮正确手指
+- 句子朗读：20 句整句拼读，逐字母高亮，整句无错 +5 分
+- 闯关积分：累计正确字数升级段位 + 奖杯墙
+- 扭蛋乐园：积分抽 10 个 SVG 收藏（三档稀有度），重复返还积分，收藏册集齐庆祝
+- 背景音乐：顶栏音符按钮，点击开关，4 首莫扎特舒缓乐章自动循环，音量 0.35，默认开启（首次交互后播放）
+
+## 验收标准
+
+- [x] 单文件 HTML，双击浏览器打开即可用（离线可用）
+- [x] 内联 JS 通过 `node --check` 语法校验，无报错
+- [x] 在线链接可访问（curl 返回 302 → 发布页）
+- [x] 手机/电脑自适应，触控按钮 ≥ 50px
+- [x] 练习进度、积分、收藏、音乐偏好存 localStorage，刷新不丢
+- [x] 家长设置可导出/导入 JSON 备份
+- [x] 无 emoji、全 SVG 图标、零外链、无第三方依赖
+- [x] 旧版数据自动迁移兼容（字符串词库 → 结构化词库）
+- [x] 背景音乐为公有领域录音，可安全公开使用
+- [x] 音乐转码为 MP3 格式，Safari 全平台兼容
+- [x] 音乐默认开启，处理浏览器自动播放策略（首次交互后播放）
+
+## 遇到的问题
+
+### 资料库部署参数名错误
+
+**问题**：覆盖更新已有页面时误用 `--node-id`，脚本报「文件不存在」。
+
+**解决**：查阅 `import_html.py` 源码确认覆盖参数是 `--node-block-id`，重试成功。
+
+### 「+5 分」提示永远显示
+
+**问题**：完成一个词时，「太棒了 +5 分」的提示在重置错误计数之后才读取，导致只要有错也显示 +5。
+
+**解决**：在重置前提前捕获 `sess.wrongWord` 到局部变量，提示基于捕获值判断。
+
+### 首版词库偏简单
+
+**问题**：8 岁二年级孩子用首版短音节词库觉得「太简单，没意思」。
+
+**解决**：词库改为结构化对象并升级为二年级语文拼音 + KET 英语双轨，再叠加句子模式，实际强度显著提升。
+
+### 莫扎特录音版权与获取困难
+
+**问题**：用户点名要「莫扎特第22号钢琴协奏曲 K.482」，但公有领域完整乐章录音难找。
+
+**解决**：
+- IMSLP 唯一完整录音是「EU PD / 美国 non-PD」，公开链接有风险，弃用；
+- archive.org 被墙不可达；
+- 改从 Wikimedia Commons 取 Public Domain 录音，K.482 完整乐章缺失只有开头小样，最终方案：K.482 开场正主 + 三首同期舒缓乐章（No.25 行板/No.20 浪漫曲/No.27 小广板）凑成「几曲」。
+
+### 系统无 ffmpeg 且 PyPI 直连慢
+
+**问题**：系统无 ffmpeg，OGG 转 MP3 受阻；PyPI 直连下载 31MB wheel 超时；清华镜像对大文件 403。
+
+**解决**：用阿里云镜像 `pip install imageio-ffmpeg`，30 秒装好，自带 ffmpeg 二进制。
+
+### OGG 在 Safari 不兼容
+
+**问题**：Commons 原始录音为 OGG Vorbis，iOS Safari 不支持播放。
+
+**解决**：全部转 64kbps MP3，全平台兼容；HTML 的 `<audio>` 用 `preload="none"`，3MB+ 音乐不阻塞首屏。
+
+### 浏览器自动播放策略拦截
+
+**问题**：用户要求「音乐默认打开」，但浏览器禁止带声音的媒体自动播放。
+
+**解决**：默认偏好 `on=true`，页面加载时 `tryAutoplay()` 主动尝试播放；被拦截则监听 document 首次 click/keydown/touchstart，用户在页面任意交互后自动播放——孩子一开始练字（点键盘）音乐就响，无需专门找音乐按钮。
+
+## 安全与限制
+
+- **数据存储**：练习数据、积分、收藏、音乐偏好存各设备浏览器 localStorage，换设备不自动同步，建议定期在家长设置里导出 JSON 备份。
+- **在线部署**：`workbuddy.link` 链接是资料库页面的公开分享地址，删除资料库页面后链接失效。
+- **音乐版权**：4 首录音均为 Wikimedia Commons 上的 Public Domain 录音，可安全公开使用；如替换音乐须同样确认录音授权状态。
+- **AI 生成内容**：词库、句子为预置内容，家长可在设置里增删调整；吉祥物图标由 AI 生成本地处理，无第三方版权风险。
+- **自动播放合规**：音乐遵循浏览器自动播放策略，不强制带声音自动播放，需用户首次交互后启动。
+
+## 可以怎样复用
+
+- **改词库适配不同年级**：家长设置里支持「拼音|汉字」格式，改一行即可换成语数、英语、古诗等任意内容
+- **调每日目标数**：家长设置里 10–500 可调，适配不同强度
+- **换扭蛋主题**：修改物品池 SVG 即可换成恐龙、太空、公主等孩子喜欢的主题
+- **换背景音乐**：替换 `MUSIC` 数组里的 base64 数据即可换任意公有领域音乐（注意 Safari 兼容用 MP3；控制单首时长与码率避免 HTML 过大）
+- **迁移到其他学科**：同样的「练习 + 目标 + 积分 + 奖励 + 音乐」框架可复用到口算、英语单词、古诗背诵等场景
+- **升级为动态页**：如需跨设备同步成绩，可再升级为资料库 database 动态页
+
+关键经验：
+
+1. **先问清两个变量再动手**：词库类型和每日目标数决定了产品方向，开工前确认避免返工。
+2. **一轮只加一个功能**：每次迭代只处理一个反馈点（难度 → 句子 → 奖励 → 图标 → 音乐），每轮都能独立验收。
+3. **改代码后必须跑语法校验**：每次修改后用 `node --check` 校验内联 JS，早发现早修复。
+4. **覆盖部署要看源码参数**：资料库覆盖更新用 `--node-block-id` 而非 `--node-id`，不确定时先读脚本源码。
+5. **古典音乐内嵌先查录音版权**：作品公有领域不等于录音公有领域，必须确认具体录音版本授权；Commons 是可靠 PD 源，archive.org 国内常不可达。
+6. **大文件内嵌用 preload="none"**：base64 音频写在 HTML 里仍可做到首屏不阻塞，关键是 `<audio preload="none">` + 按需 `loadMu()`。
+7. **自动播放策略绕不过**：带声音的媒体不能纯自动播放，「默认开 + 首次交互后放」是合规且体验最好的折中。