KK魔方 · 开发优化日志

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 格)、角/棱色组合法性及重复块排查、角块扭转与棱块翻转守恒( mod  3\bmod\,3 与  mod  2\bmod\,2)、角/棱置换奇偶性一致。

    • 内置 50 条合法状态本地 MRU 历史记录(含六面展开 SVG 缩略图)。

  • 摄像头扫描填色初版(scan-module):

    • 采用「6 面连拍存原始 RGB + 中心块实测色动态覆盖锚点 + CIE Lab 空间统一重判」两阶段流程。

v1.1 · 扫描模块深修与算法升级(Commit 97510a6 · 234,823 B · MD5 b73f7053…)

针对初版扫描填色在真机交互与复杂光照下的痛点,完成一轮底层重构与 Bug 修复:

  • Bug 修复:

    1. 选框缩放死锁:修复 pointermove 中外层误用 Math.max(..., Math.min(...) * 0.95, ...) 导致选框一拖动即锁定屏宽 95% 且无法缩小的缺陷。

    2. '?' 格点击死锁:修复跳过某面后核对页点击 '?' 格仍停留在 '?' 无法切换颜色的问题,改为首次点击切入色环首色 COLOR_ORDER[0](实测 D0 点一次切换为 Y)。

    3. 中心块误改防护:核对页点击中心块(i === 4)直接拦截锁定,避免误点破坏 9/9 色数平衡。

    4. 兜底字符统一:修正 applyAll() 中 fallback 混入颜色码('Y')而非面字母('U')的隐患。

  • 采样性能与抗偏色算法升级:

    1. 整帧单次读回:sampleGrid() 消除二重循环内数千次 getImageData(xx, yy, 1, 1) 调用,改为整帧一次读回内存遍历。

    2. 抗反光截尾均值:采样区按像素亮度排序后丢弃最暗 20%(黑边阴影)与最亮 20%(UV 贴纸高光白斑),只保留中间 60% 求平均。

    3. 彩度动态权重:在 labDist 中引入 LAB_LOWC_CUT = 18,当 min⁡(Csample,Canchor)<18\min(C_{\text{sample}}, C_{\text{anchor}}) < 18 时保留满额 ΔL∗\Delta L^* 权重(防止 2700~3000K 暖白台灯下白贴纸误判为黄),高彩度色块将 ΔL∗\Delta L^* 降权至 0.45。

    4. 容量约束全局最优分配 + 锚点精修:新增 globalAssign(),利用“48 个非中心格每色必占 8 格”的先验约束替代逐格贪心,消除暖光下“10 橙 8 红”等数量越界;并配合两轮 refineAnchors()(取同类样本中位数 Lab 更新质心)进一步消除中心块反光偏差。

  • 防拿歪与群论纠偏闭环:

    1. 核对页实时诊断:接入 renderScanVerdict(),实时显示 6 色计数条与 diagnoseFacelets() 体检结果。

    2. 拍歪一键转正(findFaceRotation):仅旋转单一面内部 9 格,遍历 6 面 × 3 个旋转角(18 次诊断 < 1 ms),8/8 随机打乱旋转测试全部精准找回并一键转正。

    3. 邻面方向引导(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词典」作为零广告、纯本地、带专属家族名字的桌面应用,本身就是一份极其用心的父爱作品。

  • 精准击中亲子学魔方的两个死穴:

    1. 符号空间化:通过 0.25× 慢速动画 + 整层描金 + 环绕色卡,消除了孩子看纸质箭头或 R' / U' 字母记号时的方向迷茫;

    2. 把“任何失误”变成“现场教材”:孩子拧乱实体魔方后不再会陷入沮丧或只能拆块重拼——掏出手机一扫,既可以用「最短解」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 彩蛋”的方向只有三个:

  1. 防熄屏(Wake Lock):照着 120 步层先法慢慢拧实体魔方时,播放期间请求屏幕常亮,避免手机中途锁屏;

  2. 求解内核升级:若未来追求极致冷启动速度,可将 cubejs(初始化需 1~2 秒)替换为陈霜的 min2phase.js(初始化约 0.35 秒、三轴+逆向联合优化);

  3. 高阶/异形扩展:等哥俩突破三阶后,顺着同样的单文件思路扩展二阶(Ortega)或四阶(降阶法)模块,甚至在文档库里加一个直接从笔记跳转到「KK魔方」对应演示情况的交互锚点。


一句话评价:

「KK魔方」是一次把硬核算法(群论、IDA*、CIE Lab 空间匹配)、扎实的前端工程(零依赖单文件、Web Worker、PWA)与温柔的家庭教育需求结合得恰到好处的作品——它不仅帮你们父子高效攻克了魔方,本身也是一份值得写进技术履历、也值得留给两个孩子长大了回头看的漂亮作品。