new-substep-solver

name

new-substep-solver

description

用户要造一个新求解器时用。**先分流**:3x3 子阶段 / 大状态空间(需 Rust+WASM+大表+真题统计管道)= 范本 block222,完整流程 solver/VARIANT_PLAYBOOK.md;非 WCA 小状态整解(可整枚举,如枫叶 Ivy 29,160 态)= 纯 TS 全 BFS,**不碰 Rust/WASM/管道**,范本 packages/client/lib/ivy-solver.ts(见正文 §0)。Triggers: "造个 X 求解器", "新求解器", "枫叶魔方求解器", "ivy 求解器", "非 wca 求解器", "小魔方求解器", "roux s1 求解器", "eoline 求解器", "petrus 求解器", "new substep solver", "加一个 step solver", "块求解器", "新变体", "new variant solver".

新求解器

§0 先分流(造任何求解器前先判这一步)

• 借用必注明(铁律,2026-06-22):求解器用了别人的东西(cstimer 移动语义照抄 / wrap cstimer 自带 solver 当引擎:dino=redi、mpyrso=两阶段 / crz3a=站内 kociemba / STM=Korf / cubelib 等)→ ① solver 文件头注 + /code/solvers/_fleet.ts 方法文案写清出处,② /about 的 credits_data.json 补/更新一条(已收录 ~30 条,先查重)。无出处不发。
• 求解器的正确性判据禁同引擎自证(铁律,2026-07-26 sq1):「打乱∘解 = 还原」必须用另一套状态模型判(SQ1 用 shared applySq1Scramble 的 tnoodle 24 槽件位;其它拼图用 cstimer moveTable / poly3dlib 几何,node:vm 加载上游即可)。拿求解器自己复查(solve(打乱+解).len===0)只证明它的 goal test 自洽 —— SQ1 页就这样带着「解根本不还原」上线了两年多:那份 gsolver 移植只把块分成 {顶棱/顶角/底棱/底角} 四类、不跟踪赤道,单层转 (1,0) 被判「已还原」。写测试先问「判据和被测代码共享假设吗」。
• cstimer 的随机态 scrambler 就是个求解器,能反过来用(2026-07-26 sq1):上游只暴露「生成」(Search_solution(c) 返回从还原态到 c 的串)。求解 S = 建 state(S) → 拿到达串 X → 在记号层取逆返回 X⁻¹(state(X)=state(S) ⇒ S·X⁻¹=id),零搜索内部改动。两个坑:① 状态要正向建 —— cstimer 形状模型只索引「切割线没劈着角」的位置,逆态常劈着((2,0) 从还原态转出来就劈着,合法但切不了刀)→ 劈着时先补最小对齐层转,solve(S)=(a,b)+solve(S+(a,b));② 输出要过一遍消步(相邻两刀相消 / 连续层转并进一个括号),否则 12c4 步数虚报。落地 = 给 tools/cstimer-scramble/scramble/<x>.js 加 solveScramble+selfCheck → scrambler.worker.js 的 SOLVERS 加一行 → 客户端 cstimerSolveByKey(key, scramble)(WCA 项目别塞 CSTIMER_EVENTS,那张表被 CI 锁给非 WCA 舰队)。上线要 rsync tools/ 到静态站,push 不够。
• 从零 reduction 先验 gadget 再动手(铁律,2026-06-22 heli/helicv/prcp/sia 批):TIER C/D 从零 reduction 动手前,先从几何 bit-exact 导出 piece model(逐 facelet 对 cstimer moveTable / poly3dlib apply),再搜「每个件型的纯 3-循环 commutator 是否存在」(2-gen + 浅 setup,bounded 别 OOM)。存在 → 可建(heli=角+4 棱轨道、helicv=+17bit 奇偶,均成);不存在 → 早红灯延后、别硬磨:件强耦合(prcp/giga 五魔系角棱:2000 万 comm 全是 5-循环、无纯 3-循环)或子群太深(sia 系棱 intoH 深度 19)= BLD 专属引擎 effort-gated epic,非一轮 loop 单元。
• 复用兄弟单元 reduction 前必重验「同群」(铁律,2026-06-22 helicv):共用 cstimer 打乱生成器 ≠ 同置换群 —— helicv 共用 heli 的 adjScramble(同 12 token)但 curvy 切多了 12 棱件、群大 256×(3e21),盲抄会建错;先从几何 bit-exact 重导 piece model 确认同群,再决定复用 / 另写(本项目兄弟文件 cuboid334-337 即先例)。
• poly3dlib 深切件的 cstimer token 解析到「浅 layer-1 帽」(铁律,2026-06-22 ctico):深切多面体(ctico/giga/prcp 都是 poly3dlib)从 cstimer 打乱 token 建 piece model / 算 |G| 时,token 经默认 makePuzzleParser 解析到的是浅层 layer-1 cap(getTwistyIdx('1'+token)),不是深层 getTwistyIdx(token);用错层会得到一个极小的纯旋转群(order 60)+ 离谱的 |G|(ctico 探针一度算出假的 7.1e34,真值 12!·5¹²·20!/80 ≈ 3.556e33)。建模 / 报 |G| 前先确认 token 对的是哪一层(用 bit-exact 对拍 moveTable 自然会暴露层错)。
• 大状态空间 / 3x3 子阶段(需大表 + 真题统计管道)→ 走下面的 substep 一页纸 + solver/VARIANT_PLAYBOOK.md(Rust + WASM)。
• WCA 项目也可能纯 TS 可证最优(别默认「WCA = 上 Rust」):群结构能因子分解成几张小表时纯 TS 就够。范本魔表 lib/clock-solver.ts —— 群 ≅ (Z₁₂)¹⁴ 阿贝尔,前后各一张 Z₁₂⁴ 表(双侧枚举 + 迭代加深),~17 ms/次、零下载表、零 worker,却算穿 12¹⁴ = 1.28e15 态。判据 = 有没有正交坐标块,不是态数大小。上 /code/solvers 别塞 NONWCA_TS(event 集被 CI 锁死 == CSTIMER_SOLVABLE_IDS,且 A/B/C/D 四档讲的是非 WCA 状态空间打法)→ 单开一节。
• 小状态非 WCA 整解求解器(状态 ≤ ~10^6 可整枚举,如枫叶 Ivy 29,160 = 81×360)→ 纯 TS 全图 BFS,绝不碰 Rust/WASM/下载表/数据管道。范本 = packages/client/lib/ivy-solver.ts + _IvySolver.tsx + gen/_svg/ivy_svg.ts(2026-06-20)。固定套路:

批量给 /scramble/gen 全部非 WCA 魔方造求解器 → 有专门 loop solver/NONWCA_PUZZLE_LOOP.md(/loop 继续造小魔方求解器)。注意不是所有都能全 BFS:分四档 —— A 现场全 BFS 最优(≤~2e6 且现场 build <1.5s、常驻 <~100MB;态数小≠现场可行 —— bic 1.1M 态却 7s/550MB、移动崩,应落 B)/ B build 预算表(~2e6–5e7,发 .bin.gz 查表)/ C 单实例 IDA* 最优(滑块如 15 数码)/ D 近最优(大型扭转 / jumbling,逐个独立工程,random-state 的可复用 cstimer 自带 solver)。下面七步是 A 档(Ivy 范式);B/C/D 的 delta 见该 loop §0.5/§4。

1. 移动语义照抄 cstimer(tools/cstimer-scramble/scramble/*.js,逐字段),整图 BFS-from-solved 复现 god-number 直方图自证正确(独立 BFS 交叉验证)。
2. 求解器 UI 仿 _Sq1Solver.tsx,接 /scramble/solver 的 event= dispatch + SolveTabs:非 WCA 无官方图标 → appendEvents 走 textLabel;HAS_DISTRIBUTION 加该 event。接线必含:给 /code/solvers/_fleet.ts 的 NONWCA_TS 加一行(档/质量桶/态数/God 数/方法),CI 守卫 tests/code-solvers-fleet-sync.test.ts 锁其 event 集 == CSTIMER_SOLVABLE_IDS,漏登记红。
3. 分布数据源按是否 WCA 分(WCA 项目的示例打乱一律走真题语料管道、禁自造;analyzer 没 Rust 版就照 *_analyzer.exe 的 CLI 契约写 TS 版 —— stdin 一行 = 块路径、产 <块>_<key>.csv、[PROG] 进度、PUZZLE_EMIT_SOLN=1 加 soln 列,范本 src/clock_analyzer.mts,update_puzzle_stats.ps1 注册表填 tsx 而非 exe;真题语料还没灌时,全空间被算穿的 WCA 项目可先拿精确表上线 —— WCA 打乱是均匀随机态,精确表就是它的极限分布 —— 真题直方图灌进来再叠成对照序列):WCA 项目 → 真题语料管道(skill update-scramble-stats,带比赛归属示例 + 时间线);非 WCA 小项目(A/B 档)→ 穷举全状态,分布 = 全空间精确直方图(数据现成在 solver 里,无管道)。范本视图 stats/_components/IvyDistView.tsx,接 stats 页 event=== 分支 + availableEvents.add + appendEvents。
   • TIER C/D 大状态空间(铁律,2026-06-21):分布必须离线预计算(build 脚本 → 静态 stats/scramble/dist_<event>.json,经 statsUrl fetch),严禁浏览器现场求解采样;状态空间巨大时由 build 脚本取合理样本数 N 离线算好,页面只 fetch+渲染;新 build 脚本接入 puzzle-stats 管道。 复用 packages/scramble-stats-build/src/build_puzzle_sampled_dist.ts(参数化 event + N,import 纯 TS 求解器、用其 cstimer 同款随机生成器采样;REGISTRY 加一行 + update_puzzle_stats.ps1 的 $SAMPLED_DIST_EVENTS 加 event)。范本 DistView = Cuboid335DistView.tsx(纯 fetch+渲染,零求解器 import)。详见 solver/NONWCA_PUZZLE_LOOP.md §0.0 #6 / §0.5 / §0.6。
   • 采样分布出炉先验形状再发(铁律,2026-06-22):双峰 / 有空档 / 某峰边缘正好卡在求解器某常量(optimal-shortcut cap、phase 下限、IDA* bound、采样预算)= 大概率求解器假象不是魔方本身 → 必须自查、别直接发。退化单柱(如全 {'11':N})= 求解器偷工(返回 scramble⁻¹ 只原路退回)。能用魔方结构(奇偶分支等固定多几步)解释第二峰才放行;否则抬 cap / 修求解器后重生。锚:335 双峰=捷径 cap 卡 12 而真最优区 9-16(已修);ssq1 双峰=假象(已修 4e869a09d):固定 ~14 切纯棱奇偶校验生成元整块加到 ~41% 解上=离散第二峰(同 bsq 那类未优化构造撑长),非真奇偶分支;修=把奇偶校验折进形状解(挑 角奇偶⊕棱奇偶=0 的方块到达态,+1 切均摊),分布塌成单峰(mean 28.1→23.0、max 41→28);ssq1 初版单柱=偷工(已打回);bsq=真 bug + 真结构并存:阶段搜索曾按「宏个数」而非真实步数(度量错,已修 Dijkstra 按 fragment-最短),但修后多峰仍在 —— 穷尽验证(全 14,633 短宏对组合)证明是受限 </,(1,0)> 下角/棱距离本身分段(120-近子群 ≤6 vs 600-远陪集 ≥9 的 7-8 空档 + 棱 3-循环地板 8)→ 真实结构,保留不抹平(2026-06-22;教训:修完度量 bug 要重验残留形状,别假定残留也是 bug;且这是「有界约简法的分布」非「魔方真最优分布」)。通则:① 多阶段 reduction 每个阶段的搜索必须按最终报告的步数 metric 最短,不能按「宏/阶段个数」最短(宏长不一→lumpy 多峰);② 多峰先分类再动手 —— 全 BFS/精确表的 dist 是真分布(多峰也合法,别「修」掉真相),奇偶分支合法,唯「求解器度量错 / 卡常量 / 偷工」才是 bug;③ 存量求解器也要逐个扫 dist 形状,不只新发的(2026-06-22 用户要求全量审计)。
4. 示例自造:枚举每个最优步数档的状态、反推最短打乱当示例(ivyExamplesByLength),不需要比赛语料(别再说「非 WCA 所以没示例」)。
5. 下载按钮:必给「下载全部状态」CSV(optimal_length,scramble,含 identity 行)+ 单步数 txt;数据走 ivyAllScramblesByLength,客户端 Blob 下载。
6. 状态图:从 solver 状态推导的 net SVG(ivy_svg.ts 复用 skewb 面切分;颜色全由状态推导 → solved 每面纯色自证),接 ScramblePreview2D 的 HAS_PREVIEW + dispatch,全站复用。
7. 测试:独立 BFS 验最优性 + 全枚举计数 == 分布 + 渲染 solved 纯色 + frame 三角恒定。typecheck + 守卫(i18n 用 tr、真 <button>)。

---

substep 求解器(3x3 / 大状态空间)

先整读 solver/VARIANT_PLAYBOOK.md(语义设计 → Rust → WASM/UI → 统计 → 发布全链路 + cstimer 语义速查表),范本代码 = solver/src/block222_solver.rs 全家桶;多目标/IDA* 范本 = roux_s1_solver.rs / block223_solver.rs;零盘表自包含范本 = eoline_solver.rs / dr_solver.rs;扭曲共轭 + 盘缓存 nibble 大表范本 = f2b_solver.rs(2026-06-10)。cstimer 3x3 求解器语义已全覆盖,新增只剩非 3x3 puzzle 与 HTR。

一页纸版:

1. 语义:件集合(面交集推导)→ 状态空间(乘积坐标,常量都在 cube_common::state_space)→ ≤3000 万态走全空间精确距离表,否则 IDA* + max(子目标精确表) 可采纳启发式(范本 block223:复用 roux_s1 全表 + 角2×棱2 小表)。深目标(均值 >11 步,如 f2b)小积表 max 顶不动,要上「接近完整目标的子集」大表(>1G 态走 nibble 落盘 + mmap,见 f2b pt9);对称双块用扭曲共轭(同一张表,sb 步进走 rot_map[2][m]);轴类目标(EO/DR)对面底色同值、y 不变,get_stats 少跑 yk。慢变体独立 CSV(别并进已满灌的 CSV 逼全量重算)。
2. 视角:1 个规范位置 + alg_rotation(6 底色)× rot_map(y^k)共轭;标签用探针法 face_map;CSV 每视角列 = 等价位置 min,列序 z0/z2/z3/z1/x3/x1。每视角可有多目标(fb_square 前/后双方块 = 双 pt 双 solved 索引,取 min)。
3. Rust:solver 模块(双轨 new/from_tables)+ analyzer bin(suffix _<变体名>,一个 bin 可输出多 stage 列)+ 测试三件套(独立运动学暴力对照是金标准;大空间用 radix-24 Vec 替 HashMap)+ e2e。枚举器必防「无效尾动」:子状态已全解(启发式 h==0,多分量取 max+额外谓词)却仍有 depth 时跳过递归(else if h > 0 { recurse }),否则次优枚举吐「更短解+一步废动」(如 XCross 成型后再 U);最优解不受影响,回归测试照 xcross_solver::enumerate_no_redundant_trailing。详见 playbook §1。
4. WASM 重建仪式 7 步(build_wasm.ps1 → copy → worker 手维护 → client TABLE_SETS/V bump → pool → StageSolver → playwright 桌面+手机验收,native↔WASM 逐格相等)。多个相关方法共享表时合并一个 WASM 类 + 一个 need(范本 Roux223SolverWasm:4 阶段 flat stage id,重表 RefCell 惰性建)。
5. 统计:两套数据集首灌 + update_cross_stats.ps1 五处注册(数字变体名键加引号)+ backfill 两处 + build.ts VariantSpec + stats 页三处 + 发布(先 push 代码等部署,再 scp static,否则旧 bundle 撞新 JSON 崩)。
6. 主页近期打乱:build_recent_scrambles.ts VARIANTS(块类变体加 metrics: [stage名])+ RecentScrambles.tsx 三处(VARIANT_ORDER/VARIANT_LABEL/METRIC_ORDER+LABEL)→ 重跑 build:recent-scrambles。
7. /scramble/gen 比赛页(标准步骤别漏,六处见 playbook):build_comp_steps TARGETS → useCompSteps → TNoodleMode(VARIANT_SPEC+引擎 ternary)→ CompCrossAnalysis(Metric+OFFSET)→ SheetView(METHODS/STAGE_IDX/CYCLE)→ 实时兜底 hook;comp_steps_* 随 stats tar+scp 发布。
8. 命名规范:用户可见标签一律纯块尺寸(1x2x2/1x2x3/2x2x2/2x2x3),UI/JSON key 用数字(123/222/223),禁「桥式/Roux」进标签;管道名/CSV 名可以另叫(123 的管道名是 roux)。
9. /code/solvers 看板走 solvers-tables skill;commit 前 typecheck + zh:check(繁体一律 conv.mjs 取值)。