当前 0.21.0 / 交接1.54.0 / 2026-10-14：最新600秒522候选0交付，41个完整候选丢卡点。新增逐插入模式保留/核心历史键、辅助形状摆向与位置/时序联合搜索（同面积同Cocos尺寸、白名单和固定序列优先）、同试摆有界邻居缓存；完整回放/独立审核/原五档门槛不变。稳定最高档仍未解决，实际实验见本轮案例与算法26节。 Mac生成 / Windows生成 / 分析台。重开核0.21.0，旧服务和发行包不会自动更新。下方为历史。

当前 0.20.0 / 交接1.53.0 / 2026-10-13：最新600秒任务498候选/0交付，构造599秒。新增永久轴门位对齐、同动作改道/核心停车重规划、多块联合前向检查、束去重与路线深度预算；完整回放/独立审核和原五档门槛不变。局部真实反例修复，但30秒24候选仍0交付，稳定高难未解决。算法25节 / 本次证据 / Mac生成 / Windows生成。需重开入口核对0.20.0，旧服务/旧发行包不会自动更新；不停止用户已有任务。下方为历史版本。

当前 0.19.0 / 交接1.47.0 / 2026-10-10：针对最新600秒失败，时序节点改当前模型单步增量执行（接受插入仍完整重放），增加机关依赖排次序、锚点/两两停车前向检查、统一L形区域口径、阶段反例修复和短循环规避。页面显示稳定原因分类、内部约束检查/最深辅助进度，下载含部分棋盘（不能交付）。实际算法24节 / 失败与验收 / Mac生成 / Windows生成 / 分析台。重开核0.19.0；旧服务不会热更新，不擅自停止。原门槛不降，最高档短测仍0交付，稳定高难尚未解决；查重表示/算法/库不变。下方0.18.0及更早为历史。

当前 0.18.0 / 交接1.46.0 / 2026-10-10：核心全解→MRV时序插入辅助块，每次加入保持完整重放路线；独立捷径早筛→精确区间/最终模式审核，不再主要靠填盘后重新碰运气找全解。按模式受益块通路局部修复，失败样本/种子/配置/耗时可下载。操作负担门槛未降，结构证据/误选代价/人工趣味分开；完整联合形状门位CSP和稳定最高档仍未完成，不能把功能回归当命中率保证。实际算法23节 / Mac生成 / Windows生成 / 分析台。重开确认0.18.0，旧服务不热更新。查重1.1.1表示/算法/库不变；三台影响与固定/留出验收见根PROJECT_PROGRESS第5/12.1节。

以下为历史记录。

当前 0.17.1 / 交接1.45.2 / 2026-10-10：核心角色与机关依赖共同预检并预留三核心；自动块数适配，手填冲突直接拒绝，不删必选机关。共享求解/首消/模式/决策图增加内存软水位、压力回收和安全未知返回；普通移动共享不可变计数，模式审核改父指针。生成继续搜索，分析显示内存证据，不放宽难度或必要性门槛。实际算法第22节、测试/600秒验证与限制见根项目记忆5/12.1。请重开Mac生成 / Windows生成、分析台，确认0.17.1。查重1.1.1算法/库不变；无Cocos/Windows实机。以下为历史版本记录。

最新 0.17.0 / 交接1.45.0 / 2026-10-10：3档M1、4/5档M2核心合法事件先行，再MRV约束回溯填辅助块；失败可沿反例通路作合法局部修复并重新独立验收，不只是换随机种子。1/2保留反向插入族。生成/分析新增前中后准备及必要模式证据面板，计划不作证书。实际程序说明第21节逐函数解释数学约束/搜索/复杂度；完整门位形状联合CSP、多核嵌套和稳定5档仍未完成，不把新版本等同于命中率问题已解决。默认600秒及严格交付保持。请重开Mac生成 / Windows生成、分析台，确认0.17.0。查重1.1.1算法/库不变。固定种子真实结果及三个工作台影响矩阵见根项目记忆5/12.1；下面为历史实施。

最新 0.16.1 / 交接1.44.1 / 2026-10-10：默认整批600秒（可缩短）；旧120秒默认一次可见迁移。页面实时显示已生成达标关数、候选累计/淘汰与查重退回，结束后保留阶段原因及统计。600秒不保证最高档必成、不降低验收。 Mac打开 / Windows打开，请核0.16.1；120秒原因诊断及统计实现。分析/查重算法和库无需因此变化，三台矩阵见项目记忆12.1。以下0.16.0及之前为历史默认。

最新 0.16.0 / 交接1.44.0 / 2026-10-10：数量表示最终达标交付数。失败/过易/查重重复/模式未知会继续搜索，直到足量、整批预算到限或取消；不使用简单替补。默认整批120秒，网页可改1～600秒，后台显示实际交付数/候选/轮次/原因并可取消，已经完成的关卡保留。自动3～5档新增空间事件构造与独立审核原型，M1/M2角色域＋关系引导束搜索＋(s,m)反例；真实报告、空间扰动参数消费与auto0～2机制已修。短预算各20seed全超时，30秒seed1 M1达标/M2超时，不是稳定最高难能力已完成。请重新打开Mac生成 / Windows生成，核0.16.0；分析台共用模式审核。查重1.1.1算法/库不变。下方0.15.0及之前为历史记录，当前边界以算法2.2、理念5.6和项目记忆为准。旧版/诊断候选接口明确标diagnostic-candidate，不是正式达档交付。

2026-10-10 / 交接1.43.2：卡点数学构造与下一步实施合同已写入同一理念5.5；形状资源/阶段事件/(s,m)模式反例、M1/M2参数化构造与验收是待授权方案，不是新运行能力。算法说明2.1联动，运行仍0.15.0，无需重启；Mac生成 / Mac分析。

2026-10-10 / 交接1.43.1：按用户要求重写算法说明2.0，给出真实调用链、状态、DP/BFS/束搜索/A*、公式与构造/检测/待实现矩阵。运行仍0.15.0，本轮未改算法。已确认默认auto只抽0～1机关、standard未消费高难scramble参数、目标未命中仍可返回；design.md通用瓶颈文案待修，不能作为设计证明。下方历史“目标扰动/最高趣味”描述以新审计边界为准。诊断：node scripts/diagnose-design-wiring.js --full（不写关卡/不安装）。Mac生成入口 / 分析入口。三台运行语义未改，无需为文档重启；同步矩阵见PROJECT_PROGRESS第12.1节。

最新 0.15.0 / 2026-10-10：安装目标与参考语料分离，当前保存为MatchMaster；页面展示并允许保存Cocos项目根目录，旧同编号默认拒绝覆盖，明确覆盖先备份。2002已补装MatchMaster，未Cocos实玩。复制给别人后在页面重新选择其项目路径。五档改为简单/较易/中等/困难/很难，以额外连续拖动/块的证据区间为暂定操作难度；五档自动空白上限统一25%，不把空隙多少当档位。默认有限候选先匹配难度，再比较协作、交接、中盘重组与释放回报，非真实最高趣味证明。生成/分析共享趣味启发式报告，查重1.1.1不改玩法判断。请重新打开Mac入口或Windows入口，确认0.15.0。详细算法见完整说明。

最新 0.14.0 / 2026-10-10：生成参数留空即自动；切换难度保留手填值。新增机制自由搭配/范围选配/全部必选/仅普通四模式，颜色也可自动；旧配置保留，可点“恢复自动”。预检首选与最终实际选择显示在结果/设计文档，原请求保存在run.json。最多4组自动配置，仍可能预算失败，目标难度不冒充实测评分。重新双击Mac生成入口或Windows入口，确认0.14.0。分析共包版本同步、模型/评分不变；查重1.1.1语义/库无需改动。 CLI的generate规格可用 {"autoConfig":true,"difficultyRating":4,"seed":123,"mechanicMode":"auto"}；未启用autoConfig的旧规格语义不变。API/UI与CLI共用解析器，详细说明见网页说明。

最新 0.13.3 / 2026-10-10：修复普通颜色0导出导致图片失败；网页色号/色板与资源一致，旧v4配置0→10、其他色号保留，v5另存且提示。CLI/API/生成/分析/判死/导入导出共享颜色检查，colorArray仍使用零基文件编码，空序列兼容旧关。生成文件与网页安装前检查本地图集图片名，报告区分资源静态检查与Cocos实机。请重新双击启动文件，确认页面版本0.13.3；旧进程不热更新，端口可能改变。 2001颜色修正版另存，未覆盖Cocos旧关；仅3处色号改变，14拖原解回放通过，未Cocos实机。

上轮 0.13.2 / 2026-10-09：自动形状适配地图/数量/占格预算；核心与网页共享配置预检；结果页显示每关失败原因、区分0/部分/全成功。 Mac打开生成工作台 / Windows入口。请重新启动，不直接打开web/index.html。预检通过不代表布局必成或可解，求解/判死/趣味评分语义不变；三个工作台影响矩阵见根PROJECT_PROGRESS第12.1节。永久偏好：以后每次交付附相关工具/产物的可点击实际路径。

2026-10-09新增100关总时长试调建议，同目录Excel/CSV/审计JSON。离线复现（Python标准库）：python3 scripts/recommend-timer-pilot.py --csv <原CSV> --out <新的输出目录>。程序核对既有1920特征源hash，文件改变时拒绝复用旧特征；不会写关卡。20%/30%/40%为试调档而非真实缺秒模型。在线生成/分析/查重评分/API/UI不改，无需重启；不是网页调时功能，最优拖数不换算秒数。

2026-10-09补充：428、434已登记为用户认为较难的待精读设计参考，先处理此前困难数据工作；不是已学习模板或趣味认证。仅反馈/理念/交接维护，生成和分析网页逻辑不变、无需重启。

2026-10-09：玩家困难数据与设计对照报告及1484关逐项表。新增离线特征提取/限时求解/统计验证程序，复现入口见报告第8节（研究统计需Python+numpy+pandas）。低成本12项模型留出R²仅0.071，未把研究系数写入生成评分；在线0.13.1不变、无需重启，原关/SQL/库未修改。线上版本与日期未确认，最优16关不足做全库G*/P校准。三个工作台与同一理念/记忆已按约定核查维护。

2026-09-28 / 0.13.1：31精读与手工1984。生成/分析共用的路径报告新增“准备协作”：不同参与块、单格参与者、终点空位交接，网页与设计文档同步。不把它当趣味评分/必经顺序；手工关不证明自动构造器已会生成同类接力。试玩文件只在根手动关卡/1984-折桥传空/。

学习/精读也自动执行完整同步：已确认且适用的程序规则同轮落实，知识沉淀与工程实现分开验收；无需用户再次提醒，未完成项列阻碍，无关项给原因。长期约定见根AGENTS第9条及交接第12.1节。

2026-09-24研究：999/863/288/280/259五关笔记。新增可重跑研究脚本node scripts/study-selected-levels-20260924.js 新输出目录，不改原关。研究结论现已部分工程化至 0.13.1：二阶段冻结构造、首消/必要让位硬验收、整块停车与释放节点报告，非灰block23障碍统计修正。三阶段/高级组机关仍未完成。请重新启动工作台；不关闭正在运行的用户任务。面向策划的完整说明：生成器全部主要逻辑与算法。可重现程序例子：examples/staged-release.json；本轮产物在runs/release-0.13.0/，不是正式发行关。验证脚本node scripts/verify-study-release.js 新输出目录拒绝覆盖；不会安装Cocos或修改原关。

维护约定（2026-09-23）：每次改动都按每次改动的同步验收核对生成、求解与设计分析、查重三个工作台，并更新同一设计理念、规则总表、feedback和项目记忆。相关代码/界面/报告/测试要实际同步；无关项说明原因，不能以文档更新代替功能实现。

2026-09-23 / 0.12.1：新增引擎源码行为对照，独立执行29个真实源码方法，10项对照/出口回归通过；完整109项回归通过。修正问号/开关锁移动、初始0方向计数、纸箱下方向计数及变色初态；旧固定floor等价替换停用。模型版本cocos-behavior-v2，复杂未建模组合拒签精确证书。未启动Cocos引擎，未修改旧关。独立复跑：npm run test:engine。旧进程不会热更新，重新双击启动入口使用0.12.1。用户55/56/57/58/59/60/64正样本及68局部反馈已登记，尚未精读。

2026-09-23 / 0.12.0：默认空间评分与有预算证据分析已实施。新增独立求解/判死/决策分析台，与原生成器、查重器分开启动。根目录双击1-生成工作台、2-求解与设计分析、3-关卡查重器； Mac用.command，Windows用.bat。完整说明见工具使用说明。 102项生成器测试、13项查重测试通过；界面实际上传与逐拖回放通过。未Cocos/Windows实机。以下旧版本叙述为历史记录，以进度文件最新状态和理念主文档第5.3节为准。

2026-09-11更新0.11.8：已修复不规则块出门阻挡，旧verified上界强制重新验证。完整92/92回归通过。 1983修正版与21拖解法已交付；原版无首消，旧22拖解撤回。 1979/1981另存23/24拖可行新解，原布局不动，未证最优；历史“回放/最优”须结合新更正阅读。诊断与修复。feedback32、理念1.6；未Cocos引擎实玩。正在运行的旧工作台进程不会热更新求解器；重新双击启动器打开0.11.8（不同版本不复用旧进程）。

这是一个可以脱离对话独立运行，也可以由 Codex 对话驱动迭代的 ColorBlock 关卡工程。

接手整个工作目录时，请先完整阅读根目录的 PROJECT_PROGRESS.md。任何实质性工作完成后都必须同步更新该交接文件。

全部人类反馈与执行状态见 人类反馈与关卡设计规则总表。每次学习或修改工作台/生成器，都同步维护总表与交接记录（即使没有新规则）；相关反馈写入 feedback/rules.json，不把“已记录”混同于“已自动强制”。

设计时的主入口为关卡设计理念、卡点分类与验收标准：每次迭代维护同一文档，包含卡点例子、直觉/数据双维难度、验收模板与自动化能力边界。 2026-09-11文档1.4 / feedback30：1982已获用户认可；新1983手工横闸交接，限定冻结/星星/永久单向。精确22拖/首消7、横闸准备必要，新增简单手工关隔离目标出口可达预检及缺角门回归。开局反事实和该预检用于手工打包，尚未接标准生成或网页；核心0.11.7评分/构造算法未改。现有瓶颈计数/准备序列不等于完整空间因果分析，详情在主文档第5节。

当前版本是零外部依赖的工程化 MVP，提供：

2026-09-11手工1983：7×5缺角短盘、11目标/10色、18.18%空白，以横闸与上层L交接开场；精确22拖，星星普通门尺寸分工、完整导出件回放、1920查重通过，趣味待用户，未Cocos实机或自动创作通用化。
2026-09-11手工1982：原块形状/功能不变，移动一原横条及新单格位置；单格独立准备必需、最早7拖首消。全程26拖可行/下界22，另存先消单格的30拖路线；仅手动目录，未Cocos实机。src/solver/opening.js 提供有预算宏动作首消与禁止指定块准备的反事实；穷尽与超预算严格区分，不冒称通用趣味评判。
2026-09-10手工1981：保留1979原10块/10门/地图，加1颗可最早转弯消除的单格及底门， 23拖可行/下界21；原冻结3因新增消除提前推进，不称逻辑完全相同。只在手动目录，未Cocos实机。用户评价1979更有趣、1980一般；文档/反馈/回归已同步，1981等待独立试玩。
2026-09-10：用户认可1979趣味，设计理念见docs/MANUAL_SPATIAL_DESIGN_PRINCIPLES.md。新手工1980采用左右窄通路与2颗单格递位，最少拖动范围21～24；仅在手动目录，未Cocos实机。 feedback26与总表同步；手工样本不冒充自动生成能力，核心仍0.11.7。
2026-09-10手工1979已交付：混合双格/L形/方块的小盘借位，星星+冻结3，精确22拖；仅保存在../手动关卡/1979-双角换位版/。打包脚本package-manual-1979.js只验证/导出人工母本，不冒称自动生成器已通用学会空间创作；未Cocos实机。规则总表与feedback25同步。
2026-09-10设计反馈更正：多用双格≠全用双格；1978形状构成已被用户否决。中后期空间设计研究见docs/MID_LATE_SPATIAL_DESIGN_STUDY.md，借用空间关系，不增加复杂机制。
0.11.7 修正不规则地图外边界门的Cocos编号；内凹边门暂不支持求解，明确报错。旧历史画像的矩形门位投影仅作兼容，不能用于证明。手工1978采用折角双格盘、星星与冻结， 19拖/去冻结17拖；偏好与总表同步，不代表自动生成已具备本关的通用创作能力。
0.11.6 新增早期机关字段级审核：规格用experience.mechanicStage: "early-50"，或内部关卡用 requirements.designPolicy.mechanicStage: "early-50"。拒绝方向倒计时及进阶叠加字段，不只按type检查；当前没有独立网页选择控件，也不根据关卡文件编号推断阶段。原版复学见学习笔记。 node scripts/study-early-levels.js可复跑研究；手工1977脚本仅打包验证，不负责自动创作。
0.11.5 精确A*在预算停止时输出可证lowerBound；加权搜索返回null，不用加权估值冒充最少步数。手工1976使用独立的有界验证/导出脚本（scripts/package-manual-1976.js），完整可行解与步数区间分开报告；标准自动生成仍要求原有最优证明，没有全局放宽。1975已被策划否决为太简单，转向多不等于好玩。
0.11.4 标准生成/手工打包禁止同色不同门组紧挨（含普通/星星组合和转角相接）；选位主动避让，最终静态验证兜底。1974违反此新规则，保留原稿待后续重排，不自动覆盖。
Mac / Windows 都可双击启动的本地网页工作台；
启动时自动索引 Cocos custom/Json 中的全部历史关卡；
固定 seed 的可复现关卡生成；
几何、门宽、配置和机制要求验证；
生成关卡的双向几何验收：方块/缺口边界、方块重叠、门边界与门组重叠、方块→门及门→方块颜色配对、门长度最小且充分；
0.9.0 新关卡标准策略：在原有 8×8、6 色、无内部拓扑孔、机制数量等规则上，新增空白不超过 25%、无大连续空白、形状多样、四象限均衡、同色/同机关不扎堆、障碍必须形成结构、至少一次解锁推进和中央视觉重心；
水平/垂直限定块的出口法线会在静态审核、生成选门和实际求解动作三处校验；
标准关卡先从完整通关路径反向构造布局；网页默认要求完整模型证明最少拖拽，单位格最短搜索超预算时会诚实标记为“可行路径”，不冒充单位格最优；
中央障碍使用 Cocos 原生 block 23 + color 11，在求解器中固定且不计入消除目标；
顺时针旋转门按 Cocos wall num 从小到大导出门组并循环，逆时针门只保留旧规则兼容；
玩家难度按最少连续拖拽判定：除额外让路拖拽、结构压力和机关深度外，还检查 “消除前是否先调位另一个方块”的交错消除率、最长连续直接消除和 1～3 个瓶颈块；单位格距离不参与难度标签；
0.10.0 增加参考 Level 1～50 的 elimination-flow 体验画像：尽早进入第一次消除、只保留少量让路拖拽，并保证至少一段连续直接消除；规格还可通过方块 type 和门 special 白名单严格限制实际产物机制；
叠加块遵循真实 Cocos 语义：stacking 保存上层颜色，上下层共用同一个 block 形状；求解报告仍按“空间投影、必须 Cocos 回放”分级；
0.10.1 起，选择星星机制时会为星星色同时生成星星方块/星星门与同色普通方块/ 普通门；缺少任意一项都会被静态审核拒绝，避免星星门退化成换皮普通门；
0.11.0 起，中前期关卡可按“最少拖动数/目标块”、为其他块铺路的拖动数和转向离场下界做硬验收；拐弯计数包含穿过门的最后一次转向，求解器同时限制已展开状态和已生成前沿，不会在稠密盘面上无界占用内存；
0.11.1 起，标准生成默认启用 designPolicy.requireMeaningfulStarCompanionDoors：同色普通门必须具有尺寸分工，或完整解回放中存在普通块离场时所有同色星星门均不可达的步骤。使用真实通行规则，不会人为禁止普通块走星星门；局部路径证据不冒充全局必经证明。 legacy 仅用于旧样本兼容，默认不启用此新增门用途规则，可显式启用；
手工打包也执行空白 ≤25%、最大连续空白区 ≤20% 和普通门用途审核，不再自动豁免前期爽关。旧交付保留，但重新打包时可能被新规则拒绝；1971 的方向受到认可，原版密度和两扇伴生普通门用途不合格，待新版本重排。
0.11.2 修正星星门尺寸审核：只要求容纳星星目标，不要求容纳同色更大的普通块。规划在形状白名单内偏好普通/星星尺寸分工；显式形状序列不改写。手工 Level 1973 已交付， 25% 空白、完整最少 14 拖、中央冻结反事实增加 1 拖，详见根目录 手动关卡/1973-S廊道紧凑版/。
0.11.3 增加初始近门检查：标准 minInitialExitTravel=2，排除贴门和一格错位（不含离场）。可选 secondaryMetric: 'interior-turning-exits' 严格最小化最短解的盘内转向消除数，不包含最后穿门转向。手工1974缩为8×7，16拖、所有最短解11/11块均需盘内转向；未证明全局最小地图。可选 solve(level, {heuristicWeight: 5}) 用于快速寻找可行路径，返回 feasible/optimal:false；默认权重 1 仍为精确 A*，加权估值不能用来证明最优。
历史原创性比较会统一检查旋转、镜像共 8 种刚体变换；变换后形状/机关角色占格相似度达到 90% 的候选会被淘汰，不再把整盘旋转当新布局；
模板变异支持严格受限的等价替换：无叠层单格问号 ↔ 同倒计时固定 floor，以及边缘 block 23 ↔ 不制造内部孔的边缘缺口；0.9.1 起，边中缺口必须连续至少 2 格，只有四个角落允许单格缺口；
单位格与玩家拖拽两种 A* 求解；标准密集关要求最少拖拽证明，单位格搜索超预算时输出已逐步验证的可行路径并明确不宣称最短；
28 个可靠序列化机制的生成入口和逐项存在性验证；
对开关、钥匙锁、冻结、星星、定向、问号、计数炸弹、地板、花瓣等执行离散状态求解；
对旋转、跳格、伸缩、叠加、粘合、实时炸弹等明确输出“空间投影 + Cocos 必须回放”，不冒充精确证明；
Cocos Creator 2.4.15 LEVEL_INFO/BLOCK_INFO/WALL_INFO JSON 导出；
可解性、难度、关键步骤和设计说明文档；
项目级反馈规则与回归样本入口；
“改进当前关卡 / 生成新关卡”的交互循环。

完整机制理解、数学模型和复杂度见 docs/MECHANICS_AND_ARCHITECTURE.md，网页使用说明见 docs/WEB_WORKBENCH.md，Cocos 测试方式见 docs/COCOS_TESTING.md。

快速开始

要求 Node.js 20 或更高版本，不需要 npm install。

不用命令行：打开网页工作台

macOS：双击 start-ui.command；
Windows：双击 start-ui.bat。

启动窗口会自动打开 http://127.0.0.1:4177。生成、验证与求解、历史库筛选、 Cocos 安装、生成记录和反馈规则都可以在网页中完成。网页只在本机运行，不会上传关卡；关闭启动窗口即停止服务。上次生成配置保存在当前浏览器中。

重复双击启动文件时，如果同版本工作台已经运行，会直接打开现有页面并正常退出。如果 4177 被其他软件或旧版本工作台占用，新版本会自动尝试后续端口，并在启动窗口中显示实际地址，避免新界面误连旧后端。

网页的默认参考范围是 ../colorBlock/assets/custom/Json/ 内所有可读取的 level*.json，不是某一个固定示例。历史库的实际数量会显示在首页；点击“重新扫描” 可在外部增删关卡后立即更新。

命令行仍然可用

cd colorBlock-level-generator
npm test
npm run demo

npm run demo 不是常驻程序。它只是下列固定命令的短名称，用于快速检查工程和复现同一个开关门样例，所以生成完成后会正常退出：

node src/cli.js generate --spec examples/switch-door.json --out runs/demo

你完全可以直接运行底层命令。examples/switch-door.json 只决定这个回归样例的生成要求，不是生成器默认只学习开关门关卡。需要日常使用时，推荐打开网页工作台；需要自动化、CI 或批处理时，再直接使用 CLI。

生成结果位于 runs/demo/：

internal-level.json：生成器的规范化关卡；
level1905.json：可放入 Cocos 的关卡 JSON；
validation.json：静态验证、可解性和要求验证；
solution-unit.json：单位格解；以其中 optimal 字段区分最短证明与可行路径；
solution-gesture.json：最少拖拽次数解；
design.md：简要关卡设计文档和分级提示；
run.json：seed、规格和产物索引。

常用命令

# 按需求生成
node src/cli.js generate --spec examples/switch-door.json --out runs/my-level

# 验证内部格式或 Cocos 格式关卡
node src/cli.js validate --level runs/my-level/internal-level.json
node src/cli.js validate --level ../colorBlock/assets/custom/Json/level1903.json

# 求最少单位格步数或最少拖拽次数
node src/cli.js solve --level runs/my-level/internal-level.json --metric unit
node src/cli.js solve --level runs/my-level/internal-level.json --metric gesture

# 审核后安装到 Cocos 项目（默认拒绝覆盖已有编号）
node src/cli.js install-cocos --level runs/my-level/internal-level.json --project ../colorBlock

# 进入“改进本关 / 新建关卡”的交互循环
node src/cli.js loop --spec examples/switch-door.json --out runs/interactive

# 查看或记录反馈
node src/cli.js feedback --list
node src/cli.js feedback --add feedback/cases/example.json

# 可复现地批量换色，并只缩短 floorMove=true 的 floorTime
node scripts/remap-level-batch.js --source <源文件夹> --out <全新输出文件夹> --seed 20260731

# 同时把 1841～1860 改名为 1941～1960，并缩短 type=16 的 questionTime
node scripts/remap-level-batch.js --source <源文件夹> --out <全新输出文件夹> \
  --seed <seed> --output-level-offset 100 --decrement-question-time

# 在多个历史来源中查找旋转/镜像后的近重复关卡，并复制成组号配对文件
npm run duplicates -- --source <历史关卡文件夹> --source <补充关卡文件夹> \
  --exclude 1905-1912 --out <全新输出文件夹>

所有命令失败时返回非零退出码，适合放入 CI。批量换色脚本默认处理 1841～1860，拒绝覆盖已有输出目录，并生成逐字段 transformation-manifest.json 与 audit.json，用于证明没有修改其他字段。使用编号偏移时会同步更新输出文件名与 LEVEL_INFO[0].id；问号倒计时只在 type=16 时随机减 0/1/2，且不会低于 1。查重命令以文件名中的数字作为对外关卡号，将内部棋盘和边界门一起放入旋转、镜像共 8 种方向比较；它忽略颜色、对象 ID 和倒计时，但保留挖空、功能角色、叠层、门位置和门类型。默认要求全图一致度至少 90%、有效格一致度至少 85%、占位一致度至少 90%。输出的 重复关卡清单.md 给出一一对应列表，同组 JSON 使用相同三位前缀，并由 audit.json 证明复制件与来源逐字节一致。

规格文件

规格采用 JSON，核心字段如下：

{
  "levelId": 1908,
  "seed": 2026072914,
  "difficulty": "hard",
  "mechanics": ["switch-door", "key-lock", "star", "rotating-cw-door", "horizontal-block", "obstacle-block"],
  "board": { "width": 8, "height": 8 },
  "pieceCount": 18,
  "colors": [1, 2, 3, 4, 5, 6],
  "shapes": [1, 2, 19, 20, 21, 22],
  "solver": {
    "maxStates": 10000,
    "timeoutMs": 2000,
    "allowConstructiveFallback": true,
    "requireOptimalGestureProof": true
  },
  "generation": { "maxAttempts": 500, "scramblePerPiece": [2, 6] }
}

同一个规格和 seed 必须产生同一个关卡。生成器使用派生 seed 尝试候选，因此失败重跑也保持确定性。

未写 designPolicy 时默认使用 standard。旧的小地图单机制回归样例会显式写 "designPolicy": {"profile":"legacy"}；日常生成不应使用 legacy 绕过新设计规则。问号、冻结、计数炸弹、锁和地板等定次值默认偏好至少 3。由于用户要求是“尽量避免” 而不是绝对禁止，已有或资源受限关卡出现 1/2 时会产生警告，不会被错误判为必然非法。

生成器会自动写入 requirements.strictGatePairing=true。这里的“门长度无多余”定义为：门长度必须等于该边方向上所有对应同色方块的最大 Cocos 外接尺寸；较小的同色方块可以共用这扇门，但门不能比最大者更窄或更宽。生成产物还会把 Cocos JSON 重新导入内部模型并再次执行同一套审核，回读失败时不会留下“成功生成”的报告。

困难关还可以使用 minOptimalUnitSteps、minOptimalGestures、 minExtraGestures、maxExtraGestures、minGesturesPerPiece、 minPreparationDrags、minPreparedExitRatio、maxUnpreparedExitRun、 minTurningExitRatio 和 minEarliestExitUnitSteps 设置硬约束。 minTurningExitRatio 不会只看展示解：已证明最少拖拽数为 G、目标块为 P，则只有 G-P 次额外拖动可用来把“初始不与任一兼容门同轴”的方块预先对齐。由此对所有最短解计算严格的必然转向下界；若二级搜索在预算内完成，则还会给出精确最小转向数。因此通过该门槛不只是碰巧展示了一条绕路解。只有相应指标确实完成最优证明时，生成器才接受带“optimal”的约束。1907 是方向漏洞的废弃回归样例；策划实评将 1909 校准为难度 1、1910 校准为难度 2。旧 runs/level-1911/ 和 runs/level-1912/ 曾被结构指标标为 3/5 级，但策划反馈后的 0.9.0 回归发现：两关的最少拖拽解都只有 2/18 次消除前调位了另一个块，且最长可连续直接消除 12 个块，因此已统一降为 2 级，不能再作为高难样例。

难度 3～5 不再靠同色块数量、单位格距离或集中在开局的一批额外拖拽升级。除原有颜色、障碍、中央临时锁格和低空隙门槛外，3/4/5 级的交错消除率至少为 35%/50%/65%，最长连续直接消除至多为 6/4/3 个，并要求 1～3 个中央瓶颈块。当前还没有经策划实机确认的新 3～5 级基准关；生成器宁可拒绝旧式候选，也不会沿用错误高难标签。

当参考历史关卡开启时，标准高难生成会使用“语料拓扑变异”：选择已经验证的结构骨架，生成器自行分配新颜色相位、中央障碍和临时锁，并可做受限的等价机制替换；旧路线被截断时，生成器通过局部 BFS、泊位枚举及后段形状收缩/迁位自动修复，再将完整重放路线作为 A* 上界，证明不存在更少拖拽的解。规格文件只提供目标和模板路径，最终坐标、机关分配、修复及 JSON 都由生成器产生，禁止人工修改生成后的关卡冒充产物。

机制支持级别

机制目录保留 28 个有可靠字段依据的选择项；新规则下两种逆时针旋转门在网页中禁用，其余机制可生成。支持分两级：

离散状态完整覆盖：普通块、两套块钥匙锁、门钥匙锁门、冻结块/门、星星块/门、水平/垂直块、问号块、消除计数炸弹、变色块、加时间块的空间部分、方块开关锁、固定/移动地板、花瓣和 block 23 固定障碍。A* 在预算内给出相应最优指标；标准密集关至少要求最少拖拽证明，并提供完整逐格可行路径。
Cocos 必须回放：叠加、粘合、实时炸弹、单色地块、顺时针旋转门、跳格门、伸缩杆门、顺时针带色旋转门、长短门、变色门和按钮门。生成器会写入真实字段、做静态审核并求解去掉未建模机关后的空间投影，但不会把该结果称为真实机关最优解。

不能作为新规则独立机制开放的值包括：type 10 是 type 1 + stacking 在运行时生成的上层； type 11/18/19 在 1825 个历史 JSON 中均未出现且没有初始化分支；special 8 不是正式枚举；LEVEL_INFO.gap 只允许作为显式的边缘缺口变异，内部拓扑孔仍被拒绝，而且边中缺口必须沿同一条边连续至少 2 格，只有角落允许单格缺口； special 5/11 是逆时针旋转门。 block 23 已按实际运行时行为建模为一个不可移动、不可消除的单格障碍。网页会直接显示这些原因。

与对话协作

工程文件是能力本体。用户可以自己使用网页或 CLI，也可以在本对话中提出：

“生成一个中等难度、核心是开关门、首次消除不超过 8 步的关卡”；
“当前关卡太拥挤，保留解题思路但降低回退惩罚”；
“以后不要再出现只有装饰作用的机关”。

客观错误会写成验证规则和回归测试；主观偏好会写入 feedback/rules.json 或 feedback/cases/。这属于项目内持久学习，不是对模型进行全局训练。

2026-10-12 同步：独立编辑器0.2.0新增地形/出块队列画布及组合字段；生成/分析0.19.2共享risefall拒证保护；查重1.1.3区分藤蔓/按钮/升降初态，不比较收缩时序/出块队列。基础time不叠加B组运行时加时。详细实现与测试见根PROJECT_PROGRESS第12.1节和编辑器docs/MATCHMASTER_020_UPDATE.md。

README.md Unescape Escape

ColorBlock Level Generator