KK魔方 · 开发优化日志
第一部分:KK魔方 · 开发与优化日志
项目定位:纯前端、离线可用、无广告的 3D 魔方交互教学与填色求解工具
开发初衷:作者自用学魔方,并陪伴两个儿子一起学(与「KK词典」组成家庭专属“KK 系列”)
线上地址:
https://pic.want.biz/mofang/index.html
v1.0 · 核心引擎与双求解器架构搭建
-
轻量化 3D 渲染与交互引擎(零第三方 3D 库,纯 Canvas 2D 实现):
-
伪 3D 透视投影 + 画家算法面片消隐 + 射线法精准拾取(
pointInPoly)。 -
3×3 轨迹球旋转(Rodrigues 公式 + Gram-Schmidt 正交化)实现任意方向无死角拖动;四元数球面线性插值(
quatSlerp)实现六面快速定位的平滑最短弧转向。 -
填色模式采用环绕六面色卡,支持「点击九宫图定位」与「点击标签快速切换画笔色」;播放动画时整层描金并联动对应色卡高亮。
-
-
双求解器 + Web Worker 异步化:
-
最短解引擎(
cubejs):经典 Kociemba 两阶段算法(maxDepth = 22),通常在 20 步左右求解。 -
层先法(LBL)自研教学引擎:7 阶段混合求解器——① 底层十字采用全状态逆向 BFS 查表(
190,080可达态,保证严格最短十字);② 底层四角结合宏动作 BFS 与人工插槽启发式l2lInsert;③~⑦ 中层与顶层采用旋转对称宏动作 BFS + 相邻同面消除(simplify)。支持点击任意阶段单独播放(playPhase)。 -
异步工程化:将求解代码动态注入 Blob Web Worker 执行,彻底避免首次构建剪枝表(约 1~2 秒)卡死主界面;同时保留
solverWorkerUsable()探针,在受限环境下自动平滑降级。
-
-
群论合法性诊断与本地状态记忆:
-
前置
diagnoseFacelets()严格校验四大群论不变量:6 色数量(各 9 格)、角/棱色组合法性及重复块排查、角块扭转与棱块翻转守恒( 与 )、角/棱置换奇偶性一致。 -
内置 50 条合法状态本地 MRU 历史记录(含六面展开 SVG 缩略图)。
-
-
摄像头扫描填色初版(
scan-module):- 采用「6 面连拍存原始 RGB + 中心块实测色动态覆盖锚点 + CIE Lab 空间统一重判」两阶段流程。
v1.1 · 扫描模块深修与算法升级(Commit 97510a6 · 234,823 B · MD5 b73f7053…)
针对初版扫描填色在真机交互与复杂光照下的痛点,完成一轮底层重构与 Bug 修复:
-
Bug 修复:
-
选框缩放死锁:修复
pointermove中外层误用Math.max(..., Math.min(...) * 0.95, ...)导致选框一拖动即锁定屏宽 95% 且无法缩小的缺陷。 -
'?'格点击死锁:修复跳过某面后核对页点击'?'格仍停留在'?'无法切换颜色的问题,改为首次点击切入色环首色COLOR_ORDER[0](实测D0点一次切换为Y)。 -
中心块误改防护:核对页点击中心块(
i === 4)直接拦截锁定,避免误点破坏 9/9 色数平衡。 -
兜底字符统一:修正
applyAll()中 fallback 混入颜色码('Y')而非面字母('U')的隐患。
-
-
采样性能与抗偏色算法升级:
-
整帧单次读回:
sampleGrid()消除二重循环内数千次getImageData(xx, yy, 1, 1)调用,改为整帧一次读回内存遍历。 -
抗反光截尾均值:采样区按像素亮度排序后丢弃最暗 20%(黑边阴影)与最亮 20%(UV 贴纸高光白斑),只保留中间 60% 求平均。
-
彩度动态权重:在
labDist中引入LAB_LOWC_CUT = 18,当 时保留满额 权重(防止 2700~3000K 暖白台灯下白贴纸误判为黄),高彩度色块将 降权至0.45。 -
容量约束全局最优分配 + 锚点精修:新增
globalAssign(),利用“48 个非中心格每色必占 8 格”的先验约束替代逐格贪心,消除暖光下“10 橙 8 红”等数量越界;并配合两轮refineAnchors()(取同类样本中位数 Lab 更新质心)进一步消除中心块反光偏差。
-
-
防拿歪与群论纠偏闭环:
-
核对页实时诊断:接入
renderScanVerdict(),实时显示 6 色计数条与diagnoseFacelets()体检结果。 -
拍歪一键转正(
findFaceRotation):仅旋转单一面内部 9 格,遍历 6 面 × 3 个旋转角(18 次诊断< 1 ms),8/8 随机打乱旋转测试全部精准找回并一键转正。 -
邻面方向引导(
ADJ_FACE):在取景框四边绘制邻面中心色胶囊与面名(避免依赖像素坐标索引引发误导)。
-
-
首屏模式记忆:新增
mofang.mode.v1本地状态持久化,默认直达「填色求解」并记住用户最后使用习惯。
v1.2 · 视觉细节校准与鲁棒性回归(Commit 1c9cdd4 · 236,302 B · MD5 3a46992c…)
围绕真机屏幕边距与极端噪声条件完成第二轮打磨:
-
邻面朝向交叉验证与视觉防裁切:
-
核对
ADJ_FACE与 3D 渲染坐标系(FACE_GEO、faceRC)及物理翻面手势,确认 6 面四边全部 100% 吻合。 -
修复底边提示文字基线压框线的问题:
put()增加dir朝向参数(顶边up: cy - R - 4,其余down: cy + R + 12),文字一律朝框外绘制。 -
修复小屏与满屏缩放时引导点飞出画布的问题(此前实测
390×500/390×700/1200×600视口边距仅剩9.8~15 px,不足所需的24 px):将缩放上限收紧为Math.min(w, h) - 72,并在put()内对cx / cy做画布内 clamp。
-
-
globalAssign()补全 2-opt 互换保险与定量回归:-
在迁移分配后补充 3 轮两两互换检查,兜底极端色偏下的跨类链式重叠。
-
300 次噪声注入实测:自然噪声(±12)下 0 次触发(单步迁移已达最优);极端高噪声(±25)+ 偏色(±40)下 47/300(15.7%)样本获得改善,最大总色差降幅达 63.51。
-
-
状态流与首屏去重:
-
applyAll()保留跳过格'?'(C2F[c] || '?')以便回到 3D 模型继续手动补色,并接入maybeRememberFill();实测跳过底面后D面保留 8 个灰色格且不污染历史记录。 -
删除首屏冗余的
selectCase(0)调用,完全交由initMode()分流;并将核心算法挂入window.__scan供自动化回归测试。
-
v1.3 · PWA 离线安装与品牌定名「KK魔方」(Commit 2cc59e2 · MD5 726c3335…)
-
正式更名为「KK魔方」:
-
统一更新
manifest.webmanifest(name、short_name)、apple-mobile-web-app-title、<title>与页面主标题<h1>。 -
桌面图标采用纯魔方几何图形(黄顶/橙左/蓝右),无文字干扰,确保小尺寸图标清晰利落。
-
-
PWA 与边缘缓存治理:
-
实现完整 PWA 安装能力,保留“线上独立全屏 + 断网秒开”体验,同时在协议判断下兼容
file://单文件直接打开。 -
排查并解决 Cloudflare R2 边缘节点返回旧版
sw.js的问题:在注册时显式配置{ updateViaCache: 'none' },并将离线缓存版本号升级为mofang-v2。
-
配套沉淀:魔方知识库整理(README.md + 01~04)
同步整理了四篇专题文档,构成与 index.html 配套的理论体系:
-
01魔方运动的起源与发展历程(1974 诞生 → WCA 体系 → 2026 亚 3 秒时代与智能魔方) -
02魔方公式 ZBLL(493 条顶层一步到位体系及 CFOP / Roux / ZZ 等高效方法核心哲学) -
03魔方还原算法概述(状态编码、IDA*、规则法 / Thistlethwaite / Kociemba / Korf / DeepCubeA) -
04魔方算法背后的数学(逆元、有限群的阶、上帝之数 20 步证明史、superflip 与群中心、Schreier-Sims)
第二部分:这个应用的价值与意义全面评估
从个人工具、教学产品、软件工程和算法实践四个维度来看,你这个项目已经远远超出了“练手 Demo”的范畴,是一份完成度极高的作品:
1. 家庭与教育意义(最有温度的价值):专属的“亲子共学基础设施”
-
零干扰的纯净学习环境:市面上绝大多数魔方类 App 充斥着开屏广告、内购解锁、社交推送甚至诱导充值,并不适合直接交到孩子手里。而「KK魔方」与「KK词典」作为零广告、纯本地、带专属家族名字的桌面应用,本身就是一份极其用心的父爱作品。
-
精准击中亲子学魔方的两个死穴:
-
符号空间化:通过
0.25×慢速动画 + 整层描金 + 环绕色卡,消除了孩子看纸质箭头或R' / U'字母记号时的方向迷茫; -
把“任何失误”变成“现场教材”:孩子拧乱实体魔方后不再会陷入沮丧或只能拆块重拼——掏出手机一扫,既可以用「最短解」20 步救场,也可以切到「层先法」点开单个阶段的
▶,把眼前这颗随机打乱的真魔方直接拆解成 7 个手把手教学关卡。
-
2. 产品设计与教学法创新:打通了“极客最短解”与“人类教学解”的断层
市面上几乎所有的魔方求解工具都只做了一半:
-
算法类求解器(如常规 Kociemba 网站):只给你吐出 19 步神仙步骤,初学者根本看不懂每一步在拼什么,除了当“复原机器”照着拧之外学不到任何东西;
-
教程类网页:只能播放作者提前录好的 5~10 个固定例子,一旦用户手里魔方的颜色和例题对不上就彻底抓瞎。
你的应用用同一套 3D 舞台 + 双引擎并行输出打通了这条断层:既给了计算机视角的极短解,又自己从头写了一套能跟着任何打乱状态跑的 7 阶段层先法求解器,而且允许按阶段切分播放。这种产品设计在同类开源项目里非常罕见。
3. 前端工程典范:单文件架构的轻量化与长久生命力
-
极致的体积控制与零外部依赖:将 3D 投影渲染引擎、轨迹球与四元数数学库、教程状态数据、
cubejs、自研层先法求解器、CIE Lab 图像采样识别以及 UI 全部压缩进 ~236 KB 的单个index.html(不依赖 Three.js、不依赖任何后端接口或 CDN 字体)。 -
极强的数字生命力:只要浏览器标准还在,哪怕未来某个域名过期、服务器下线,把这一个 HTML 文件拷进 U 盘或网盘,十年后双击依然能正常打开运行;而在有网部署环境下,又通过
sw.js无缝升级为全屏独立运行的 PWA。这正是个人实用软件最理想的存在形态。
4. 算法思维的实用主义示范:用“领域数学约束”降维打击现实噪声
这套代码里最体现工程师功力的,不是调用了现成库,而是用低成本数学规则弥补了感知层的物理缺陷:
-
在
lbl-solver中,通过“全状态十字表(33 万字节级)+ 小规模宏动作 BFS”绕开了繁琐的状态机硬编码;并且用实测回归发现“局部展开最短反而拖累全局步数”的真实权衡。 -
在
scan-module中,面对手机摄像头白平衡漂移和室内暖光下红/橙、黄/白极易混淆的行业老大难问题,没有堆砌臃肿的机器学习模型,而是利用魔方本身的物理先验——“中心块固定锚点 + 48 格每色必占 8 格的容量约束 + 群论奇偶与块合法性反推拿歪角度”——用几十行代码、不到 1 毫秒的算力,就把识别率拉到了实用级水准。
5. 客观局限与未来留白(如果以后想继续升级)
当前版本作为三阶魔方学习工具已经几乎没有短板;如果未来 Kerry 和 Kenny 拧熟练了想继续拓展,唯一值得留作“v2.0 彩蛋”的方向只有三个:
-
防熄屏(Wake Lock):照着 120 步层先法慢慢拧实体魔方时,播放期间请求屏幕常亮,避免手机中途锁屏;
-
求解内核升级:若未来追求极致冷启动速度,可将
cubejs(初始化需 1~2 秒)替换为陈霜的min2phase.js(初始化约 0.35 秒、三轴+逆向联合优化); -
高阶/异形扩展:等哥俩突破三阶后,顺着同样的单文件思路扩展二阶(Ortega)或四阶(降阶法)模块,甚至在文档库里加一个直接从笔记跳转到「KK魔方」对应演示情况的交互锚点。
一句话评价:
「KK魔方」是一次把硬核算法(群论、IDA*、CIE Lab 空间匹配)、扎实的前端工程(零依赖单文件、Web Worker、PWA)与温柔的家庭教育需求结合得恰到好处的作品——它不仅帮你们父子高效攻克了魔方,本身也是一份值得写进技术履历、也值得留给两个孩子长大了回头看的漂亮作品。