我先录了一套 11 节的 WorkBuddy 实战课教方法,转头用同一套方法真刀真枪二开了开源背单词项目「词光 WordAtlas」——课程里讲的创建技能、建知识库、多会话协作、二开,正好全用上了,但实战还是给了我 4 个课上没讲到的真坑。这篇把过程和坑一次讲透。
一、背景:词光是什么,我二开的又是哪一版
词光(Word Atlas)是一个 GitHub 开源的雅思词汇图鉴:7,298 个词条,一词一画,带英美双音和例句,用 FSRS 间隔复习算法安排记忆,还有一个 WebGL2 词汇星图。它最特别的地方是:无账号、无后端、本地优先,整个应用就是一套静态前端。
我做的是「学习研究 + 简单二开」,不是重做产品。本文讲的都是仓库里的开源版,不是在线站,也不是 iOS App——那两个是上游独立迭代的,功能可能有差异,我不混着说。应用代码是 MIT 协议,词库文本、插画和词条录音是 CC BY 4.0,文末按规矩署名。
二、课程讲了什么:11 节,从方法到落地
我录的这套课叫《WorkBuddy 开发背单词软件实战》,一共 11 节。它不是一个功能一个功能地堆,而是按「用 AI 编程的真实工作流」排的:
- 第 5 节 创建项目 Skill
- 第 7 节 创建 UI 设计技能
- 第 8 节 创建 Obsidian 知识库
- 第 9 节 维护 GitHub 仓库
- 第 10 节 多会话同时开发同一项目
- 第 11 节 二开背单词项目
你发现没有——这 6 节,几乎就是我这次二开实际走的每一步。
三、这次二开做了什么:时间线
课程是「教方法」,二开是「验方法」。我按时间把这次实战拆成几段:
- 启动:用 Node 22.22.2 + Vite 6.4.5 把项目跑起来,固定 8890 端口(避开另一个项目的 8888/8889),HTTP 200 跑通首屏。
- 重组目录:把源码与设计稿分目录归置,迁移被进程卡住的部分按「源存在且目标不存在才移动」的幂等规则补齐,不覆盖在途文件。
- 封装 UIDesign 技能:把「正在运行的 Web 应用」还原成 15 张可双击打开的静态 HTML 设计稿——注入确定状态、抓 DOM、内联 CSS、本地化资源、canvas 烘焙、冻结动画,再逐稿像素校验。
- 品牌二开:把「词光」改成「背单词」,链接指向白泽软件官网,署名保留上游与 CC BY 4.0 红线,全程不动 UI 源码。
- 收尾验收:
npm run build三次(首次成功、重复构建被安全守卫拦下、加--no-emptyOutDir成功),15 态视觉验收 221/221 图片加载、破图 0、非预期错误 0;单测 21/21 通过。
结果:15 张设计稿 15/15 像素达标,平均差异 0.170%、最大 1.84%,阈值 2% 全程没放宽;破图 0、pageerror 0、源站 URL 残留 0。
四、四个课上没讲的坑(现象 / 定位 / 解法)
课程能教方法,但有些坑只有真跑才遇得到:
坑 1:canvas 截图被二次采集,变成坏 PNG。
现象:设计稿里插画位置是一块米色坏图(实测 2174 字节)。定位:替换图没打标记,被资源采集器当成远程 URL 二次下载,又被 Vite 的 HTML fallback 覆盖成坏 PNG。解法:给替换图打 data-uid-canvas 标记,采集和重写都跳过它。
坑 2:loading="lazy" 在本地离线(双击 HTML)打开时不触发。
现象:首轮验收报 53 张「破图」。定位:视口外的图 complete:false 是浏览器正常行为,不是资源缺失。解法:生成前统一改 eager,等全部 complete 再判定,破图归零。
坑 3:动画 paused 停错帧,元素被隐藏。
现象:p12 场景差异 11.21%。定位:源站动画停在末帧,新打开的页面停在首帧,入场淡入元素因此隐藏。解法:不用 paused,改成 animation:none + 把终态写死成内联样式,p12 差异降到 0.00%。
坑 4:WebGL 星图逐帧差异。
现象:p08 场景 2.12% 超标。定位:WebGL 每帧渲染有微小抖动。解法:加 freezeRafMs 把 requestAnimationFrame 冻结 3000ms 抓终帧,p08 降到 1.84%,达标。
五、三条可复用方法论
- 数字先实测再落笔。 任何要写进文章或笔记的数字,都用脚本跑一遍存证据,不采信代理报告,抽查也不等于采信。这次 15/15、221/221 都是脚本实测值。
- 把 AI 当协作者,不当甩手掌柜。 多会话同时开发时,冻结一方的
add/commit/checkout/reset,只做 push 和对象级操作,等确认完成再统一提交——避免两个会话互相踩。 - 验收要能暴露问题,不能调阈值糊弄。 差异率卡 2% 就老老实实卡 2%,超标就定位真因,绝不把阈值调宽松来「通过」。
六、课程与实战,互为印证
这次二开最有意思的地方:课程第 5、7、8、9、10、11 节讲的操作,我在实战里一个没落下地做了一遍。课程是「我教你怎么做」,实战是「我用给你看」——而且实战补上了课程里来不及讲的 4 个具体坑。如果你看过课,这篇文章就是它的「现场版答案」;如果你还没看,这 4 个坑本身就是最值钱的预习。
七、边界与未验证(老实说)
- 「构建通过 / 设计稿 15 态验收通过」不等于「测试全部通过」。已实跑的是
npm run build、单测(21/21)与 15 态视觉验收;还没覆盖跨浏览器(Firefox/Safari)、高 DPI、真机 375px、2D 降级帧率与长时性能。 - 浅克隆推新仓库时连吃 3 次拒,最后定位为「浅克隆缺父提交」,
fetch --unshallow后一次成功——这是 Git 的坑,不是项目的坑。 - 词库的
sfx/音效授权还没向上游确认,本文不带任何音效 / 配乐。
八、给读者的一个具体动作
如果你也想用 AI 二开或还原一个开源前端,今天就可以做一件事:先把项目用 npm run dev 跑起来、截一张首屏,再用一个还原技能把关键页面存成可离线打开的 HTML 设计稿——这一步能逼你把「以为看懂了」变成「真能复现」,也是我这套课和这次二开共同的起点。
署名与声明:本文基于词光 Word Atlas 开源仓库(designfuchen/word-atlas,commit
0f1bae41)的学习笔记。应用代码采用 MIT License;词库文本、插画与词条录音采用 CC BY 4.0,署名Word Atlas contributors — CC BY 4.0。本文引用内容已节选改写。相关内容由生成式 AI 产出、经自动校验但未逐条人工审校;本项目不是官方雅思词表,与雅思考试主办方无关。