跳到正文
白泽软件开发

录完11节实战课,二开词光踩了4个坑

第 04 篇 AI 开发实战 AI编程

我先录了一套 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 节,几乎就是我这次二开实际走的每一步。

三、这次二开做了什么:时间线

课程是「教方法」,二开是「验方法」。我按时间把这次实战拆成几段:

  1. 启动:用 Node 22.22.2 + Vite 6.4.5 把项目跑起来,固定 8890 端口(避开另一个项目的 8888/8889),HTTP 200 跑通首屏。
  2. 重组目录:把源码与设计稿分目录归置,迁移被进程卡住的部分按「源存在且目标不存在才移动」的幂等规则补齐,不覆盖在途文件。
  3. 封装 UIDesign 技能:把「正在运行的 Web 应用」还原成 15 张可双击打开的静态 HTML 设计稿——注入确定状态、抓 DOM、内联 CSS、本地化资源、canvas 烘焙、冻结动画,再逐稿像素校验。
  4. 品牌二开:把「词光」改成「背单词」,链接指向白泽软件官网,署名保留上游与 CC BY 4.0 红线,全程不动 UI 源码。
  5. 收尾验收: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%,达标。

五、三条可复用方法论

  1. 数字先实测再落笔。 任何要写进文章或笔记的数字,都用脚本跑一遍存证据,不采信代理报告,抽查也不等于采信。这次 15/15、221/221 都是脚本实测值。
  2. 把 AI 当协作者,不当甩手掌柜。 多会话同时开发时,冻结一方的 add/commit/checkout/reset,只做 push 和对象级操作,等确认完成再统一提交——避免两个会话互相踩。
  3. 验收要能暴露问题,不能调阈值糊弄。 差异率卡 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 产出、经自动校验但未逐条人工审校;本项目不是官方雅思词表,与雅思考试主办方无关。

免费咨询 收起

想聊聊?选个顺手的方式

工作日会回复,原型范围与启动条件确认后,3 个工作日内提供核心流程原型。

加微信(个人好友)

微信号 yggaibc,长按也可复制。

拨打电话18010070052 打开微信需已安装微信

「打开微信」取决于系统是否支持 weixin://,不生效请用上方「复制微信号」。

在线填需求 →
案例可查:看项目案例 →

公众号「AI程序员张总」可看技术复盘。

更多方式:微信好友码 / 飞书 / QQ / 公众号 →

QQ 1156956636(长按复制)。二维码都在需求页「扫码联系」里。