echo-nexus/docs/04-解码系统修复-v0.1.1.md

解码系统修复说明 (v0.1.1)

问题

用户反馈「解码大量的无法通过」。经分析，根因是 generatePuzzle 没有保证生成的局面有解：随机填色后可能根本不存在一条满足「按目标顺序、四邻接、不重复」的路径，导致大量死局。

修复方案

1. 路径构造法生成器（核心修复）

重写 generatePuzzle，采用路径构造法：

1. 先随机生成目标序列 target。
2. 在网格上主动构造一条合法路径：随机起点，每步走向一个未使用的四邻接节点，长度 = target.length。
3. 把路径上第 i 个节点颜色强制设为 target[i]。
4. 其余非路径节点随机填色（60% 偏向目标色，提升多解性）。

这样至少存在一条解（即构造的路径），玩家不会遇到「怎么都过不了」的死局。

2. 精确可解性检测 isSolvable

新增 DFS 函数，从当前路径末端出发，精确判断是否存在一条按 target 剩余顺序、四邻接、不重复的完成路径。用于：

• 玩家点击后检测「此路不通」，提示撤销。
• isStuck 复用此判定。

3. 撤销功能 undoStep

新增 store action，支持单步回退（恢复节点 used 状态）。走错时无需整个重排。

4. 卡死提示横幅

当局面不可解时，顶部显示「谐振受阻，此路已无解」横幅 + 快捷撤销按钮。

5. 可行起点高亮（体验增强）

选起点阶段，用 canStartFrom 检测每个目标色节点「选了之后是否仍可解」：

• 可行起点：强光圈 + 2px 边框 + 快脉冲，引导玩家。
• 死起点：淡化(opacity 0.5)，避免玩家踩坑。

6. 旧存档兼容

init 时检测存档中的活跃谜题，若不可解（旧算法生成）则自动放回晶体队列，避免老玩家卡死。

验证结果

算法验证（1000 次/档位）

• Tier 1: 1000/1000 可解 (100.0%)
• Tier 2: 1000/1000 可解 (100.0%)
• Tier 3: 1000/1000 可解 (100.0%)
• 总计: 3000/3000 (100.00%)

模拟游玩（带可解性筛选的贪心玩家）

• 500 局: 100% 解出，平均撤销 0 次

agent-browser 端到端验证

• T1 (3×3): 通过 ✓
• T2 (4×4): 通过 ✓
• 死路检测: 触发「谐振受阻」横幅 ✓
• 撤销: 单步回退正常 ✓
• 可行起点高亮: 准确标记（4 个玫色节点中仅 1 个为可行起点，与手算一致）✓

影响文件

• src/lib/game/decode.ts — 重写生成器 + 新增 isSolvable/canStartFrom
• src/store/gameStore.ts — clickNode 可解性检测 + undoStep + init 兼容
• src/components/game/DecodeArray.tsx — 撤销按钮 + 卡死横幅 + 可行起点高亮