补充一笔画调研与关卡设计文档

docs/关卡设计规范.md

@@ -0,0 +1,237 @@
+# 数字一笔画：关卡设计规范
+
+依据当前工程的 GDD、实际关卡 JSON、规则代码、生成器和发布校验器整理。核对日期：2026-10-12。
+
+主规范适用于 `modes/01-number-stroke`（数字一笔）；`modes/03-hex-walls`（六边一笔）是独立玩法，其差异见第 9 节。
+
+本文区分三种要求：**硬规则**是规则代码或发布校验要求；**设计原则**来自 GDD 和现有内容策略；**策划建议**是用于制作、评审与试玩的补充，不代表程序已经强制执行。
+
+## 1. 设计目标
+
+让玩家通过观察、排除和步数推算，找出唯一的一条走遍所有格的路线。爽点是“只能这样走”的顿悟，以及推理完成后一笔画完的顺畅感。
+
+- 单机、离线、手机竖屏；无计时、无体力、无分数。
+- 数字玩法的 GDD 单局目标为思考 15–90 秒、绘制 3–8 秒。这是体验目标，不是已通过试玩验证的指标。
+- 大格的核心价值是“面积与步数分离”：占地更大、邻接更多，但只计一步。
+- 所有关卡、命名和资源原创，不使用第三方题库。
+
+## 2. 盘面与路径的硬规则
+
+| 项目 | 规范 |
+|---|---|
+| 格数 | `N = cells.length`，按拼块数量计数，不按占地面积计数 |
+| 坐标 | 使用整数单位网格，原点左上；制作时建议统一从非负坐标开始 |
+| 矩形格 | 允许 `1×1`、`1×2`、`2×1`、`2×2`、`3×3` |
+| 异形格 | `shape` 定义 2–4 个四向连通单位格；I/L/S/T/O 目录，允许旋转、镜像 |
+| 异形尺寸 | `w/h` 必须等于形状包围盒尺寸；偏移非负、无重复。`I4` 可通过 `shape` 表达，不能据此把 `4×1` 当作允许的普通矩形 |
+| 占地 | 拼块之间不能重叠；未被任何拼块占据的位置为空洞 |
+| 邻接 | 共享至少一条单位边才相邻；碰角、隔洞不相邻 |
+| 连通 | 整张格图必须连通；连通只是有解的必要条件 |
+| 路径 | 每格恰好经过一次；只可前进到相邻未走格；不能跳格、分叉或重复经过 |
+| 大格 | 整块是一个节点，只计一步；块内不再按小方格计数 |
+| 通关 | 路径覆盖全部 N 格，且所有数字与奇偶要求同时满足 |
+
+“一笔画”是连续路径约束，不要求玩家全程不松手。松手可保留路径并继续；点按相邻格也能追加。
+
+不引入斜走、传送、单向边、冰格、颜色门、限时等未实现机制；六边形和墙属于另一玩法，不直接加入数字玩法。
+
+## 3. 线索设计规范
+
+### 3.1 数字线索
+
+- 数字 `c` 表示该格必须是路径第 `c` 步；反过来，第 `c` 步也必须落在这个格。
+- 数字为 `1..N` 的整数，同一关不能重复。
+- 可以位于路径中段，不必给终点 `N`。
+- 有 `1` 时玩家只能从它起手；没有 `1` 时玩家可尝试任意格，但只有满足全部条件的完整路线能通关。
+- 起点未知安排在掌握基础规则之后；当前首次出现于 **2-8（总第 18 关）**，教学包全部保留 `1`。
+
+### 3.2 奇偶线索
+
+- `odd` 要求本格步号为奇数，`even` 要求为偶数；仍按整块计步，与面积无关。
+- 原始关卡同格只能写数字或奇偶，不能同时写；一关可有多个奇偶格，也可与其他格的数字混用。
+- **每条奇偶线索必须必要**：单独删除任意一条后，应出现至少两条合法解。现有 `validate` 会拒绝冗余奇偶条件。
+- 不用普通方格盘上天然成立的黑白奇偶作为无效装饰；优先结合大格、异形改变路线步号关系。
+- 当前随机生成器只生成数字关。奇偶关采用人工配置线索，再由求解器验证。
+
+### 3.3 少而有效
+
+**硬要求：每关恰好一条满足全部线索的完整路径。** 唯一性按有序步号路径计算；没有 `1` 时也必须检查所有可能起点。
+
+**设计原则：**在保持唯一解和教学效果的前提下尽量少给线索，中后期优先尝试删除端点暗示。前 8 关允许保留教学所需的冗余数字。
+
+数字线索的最简性目前不是发布校验的硬门槛；需要用 `design --minimize` 人工检查。该工具输出的是“单独可删”的线索，不能把所有可删项同时删除；应逐次删除并重新验证。
+
+## 4. 难度控制
+
+| 旋钮 | 设计作用 | 当前引入节拍 |
+|---|---|---|
+| 格数 N | 增加路线长度与信息量 | 全程；开头可小至 3–5 格 |
+| 中段数字 | 要求计算到达时机，而非只认起终点 | 1-5 专项教学；1-3 已用中段数字辅助撤销教学 |
+| 空洞 | 切断直觉近路，迫使识别真实邻接 | 1-6 |
+| `2×2` | 一步对应多个出口，形成路线枢纽 | 1-4；1-8 专项强化 |
+| 横竖长条 | 利用长边邻接，要求先判断从哪边进入、离开 | 1-9；1-10 综合 |
+| `3×3` 与异形 | 扩大出口选择、改变凹口邻接 | 第二包；首个 `3×3` 为 2-2 |
+| 线索步号差 | 拉长尚未确定的路线区间，是现有难度主旋钮 | 全程，进阶包重点使用 |
+| 不给 `1` | 加入起点推理 | 2-8 |
+| 奇偶 | 用较弱的条件筛掉错误路线 | 第三包，先缩小盘面再组合 |
+
+**线索步号差指按数值排序后的连续数字之差，不指空间上相邻两格。** 例如 N=21，线索为 `1、5、21`，差值为 `4、16`；生成器还计入最后一个线索到 N 的尾段，此例为 0。
+
+进阶数字关通常先给 `1` 与一个早期引导数字，再将后续区间拉长。当前生成器的引导数字取值是 **4–7**，即从第 1 步到它有 3–6 次转移；不要混写成固定“相隔 4–7 步”。这不是每个手工关的硬约束。
+
+GDD 的一般规模建议：教学约 8–12 格、常规 12–16 格、后期 17–22 格；基础教学与新机制教学可更小。当前数字关实际范围为 3–21 格。`N≤22` 是求解器的设计工作范围，解析器没有强制拒绝 N>22，扩展前需另做性能与手机操作验证。
+
+策划建议：一次新增一种主要认知负担，之后用旧机制组合强化；包尾设综合题，新机制包开头回落难度。不能用格数、线索少或生成器分数直接代替真人难度判断。
+
+## 5. 当前教学与关卡包结构
+
+### 5.1 入门包：10 关，手工设计
+
+| 关卡 | N | 教学目标 | 数字线索 |
+|---|---:|---|---|
+| 1-1 | 3 | 从 1 滑向邻格，自动计步 | 1 |
+| 1-2 | 4 | 必须走完所有格 | 1、4 |
+| 1-3 | 5 | 走错后可以退回 | 1、3 |
+| 1-4 | 4 | 大格只算一步 | 1、3 |
+| 1-5 | 7 | 中段数字限制路线 | 1、4 |
+| 1-6 | 9 | 空洞不相邻，先观察终点 | 1、9 |
+| 1-7 | 12 | 多处分叉，先推再画 | 1、4、8 |
+| 1-8 | 11 | `2×2` 的多出口枢纽 | 1、8 |
+| 1-9 | 11 | 横长条的进入、离开方向 | 1、6 |
+| 1-10 | 14 | 大格、长条与步数综合小考 | 1、6 |
+
+1-4 是关键验收关：新玩家必须理解“大块不是多步”。若教不会，先改盘面和演示，再增加后续内容。
+
+### 5.2 进阶包：10 关
+
+当前 N=14–21，通常含 2–3 个多单位格，数字线索通常 3–4 个。最大步号间隔由前段约 7–8 逐步抬升到 16，2-8 加入起点未知。允许生成候选，但每关必须人工审核路线、读盘和推理。
+
+### 5.3 奇与偶：6 关体验包
+
+当前 N=4–18：偶数入门 → `3×3` 上的奇数条件 → 用奇偶决定绕行 → 异形、数字、多个奇偶共同推理。可复用几何重新设计线索，但要形成新的推理任务，并逐条证明奇偶条件必要。
+
+当前共 **26 关（10＋10＋6）**。旧 GDD 中的“12 关教学”“每包 8 关”“44 关总量”是早期计划，不是现有包长与交付要求。正式包是否扩展到更多关卡，应另立内容计划。
+
+## 6. 推理、路线与操作品质
+
+以下为设计原则及策划评审建议，不能由唯一解检测代替：
+
+1. **先写推理意图。** 每关说明关键分叉、排除错误路线的依据、玩家预期获得的顿悟。
+2. **能解释为什么。** 无提示时应可由步数、端点、邻接、封闭区域或奇偶条件推出来，避免主要靠枚举试错。
+3. **大格实际参与。** 进阶关尽量让多单位格位于路线中段，进出各一次；若改成单格也不改变关键推理，需要重新评估它的价值。
+4. **不只做蛇形填满。** 避免长时间机械沿唯一走廊扫过；综合关应有需要观察和排除的选择。
+5. **错误有依据。** 误导来自“靠得近但步数不对”“先走会封死剩余区域”等规则事实，不能来自看不清边界或含混邻接。
+6. **手机上可读可画。** 数字、奇偶标记、空洞、异形凹口和共边清晰；检查窄屏适配与快速滑动，避免用极端长宽比压小触点。
+
+生成器现有过滤：多单位格不能当作者解端点；至少一个大格；按拼块中心估算的最长同向段比例不超过 0.5。这些只是候选筛选启发式，不是所有教学关都要遵守的硬规则，也不等同于“路线漂亮”。
+
+## 7. 容错与提示对关卡设计的要求
+
+- 允许踩错线索后继续画，错误格标红；不得把“错了立即失败”作为教学前提。
+- 指定步号被其他格占用时立即冲突，不能假设玩家必须踩到原线索格才会收到错误反馈。
+- 死路不会锁死或弹失败；数字玩法可点任意已走格，截掉后续路径，也可重开。
+- “补数字”只补一个确定步号，帮助缩小待解区间，不自动画路；即使玩家走错，也从真实解补数。
+- 补数可以落在奇偶格上，此时新增数字与原奇偶要求同时生效。这是对局辅助，原始 JSON 仍禁止同格同时配置二者。
+- 重开保留本局补数；退出重进恢复原始关卡。
+- “指路”：空路径指起点；正确前缀指下一步；偏离时指最后正确位置，要求回退，不沿错路继续提示。
+- 原关必须在不开提示时仍能人解，不能用补数来弥补缺失的基本可解性与教学。
+
+## 8. 制作、数据交付与验收
+
+### 8.1 制作流程
+
+确定教学/推理目标 → 铺盘并确认邻接 → 找作者解 → 配少量线索 → 求解验证唯一 → 逐项删线索复验 → 人工推理解题 → 手机操作试玩 → 排入关卡包。
+
+教学关手做；进阶可用生成器。每次修改几何、数字、奇偶条件后都重新验证。不要直接覆盖已验收的正式包来试生成参数，应先输出到候选文件。
+
+### 8.2 数据格式
+
+包字段：`mode`、`pack`、`title`、可选 `notes`、`levels`。单关字段：`id`、可选 `teach/caption`、`cells`。格字段见第 2、3 节。
+
+```json
+{
+  "mode": "01-number-stroke",
+  "pack": 1,
+  "title": "入门",
+  "levels": [{
+    "id": "1-1",
+    "teach": "滑动，邻格自动出步号",
+    "caption": "从 1 开始，滑到旁边的格",
+    "cells": [
+      { "id": "a", "x": 0, "y": 0, "w": 1, "h": 1, "clue": 1 },
+      { "id": "b", "x": 1, "y": 0, "w": 1, "h": 1 },
+      { "id": "c", "x": 2, "y": 0, "w": 1, "h": 1 }
+    ]
+  }]
+}
+```
+
+- 格 id 在单关内唯一；关 id 在玩法内唯一，建议按 `包号-包内序号` 编排。包内序号实际来自数组顺序，应与 id 一致。
+- `teach` 是设计备注，永不作为玩家文案；可记录目标、来源、参数和作者解。`caption` 才是对局教学文案。
+- 不配置供通关判定读取的答案字段；当前进阶关确实会在 `teach` 里记作者解，不能误解成文件完全不含答案。
+- 旧 GDD 样例中的单关 `pack/index/cellSize` 不在当前 `LevelDef` 中；`hintPath` 也没有对应实现。按实际类型与解析器交付，不照搬旧样例。
+- 新包需要在 `web/main.ts` 的 `packs` 中登记；正常版跨包线性解锁，单文件试玩版全部关卡开放。
+
+策划交付建议另附：关键推理说明、错误路线及排除理由、作者解、数字删减记录、奇偶删除证明、预期难度与试玩记录。作者解不要放进 `caption`。
+
+### 8.3 工具
+
+在 `modes/01-number-stroke` 中运行：
+
+```powershell
+npm run validate
+npm run validate -- 1-7
+npm run design -- 1-7 --minimize
+npm run design -- 1-7 --suggest 3
+npm run check
+```
+
+`validate` 验证结构可加载、盘面连通、恰好一解、没有冗余奇偶条件。`check` 另含类型检查和单元测试。唯一性检查至少要允许找到第二条解，不能以“找到第一条”为合格依据。
+
+### 8.4 发布验收表
+
+| 检查 | 门槛 | 方式 |
+|---|---|---|
+| 几何、数字范围、重叠与格 id | 合法 | Board 构建 / validate |
+| 连通与完整路径唯一性 | 连通、恰好 1 解 | validate |
+| 奇偶有效性 | 每条删除后多解 | validate |
+| 数字有效性 | 无不必要数字，或说明教学保留理由 | design + 策划评审 |
+| 关 id、数组顺序与包登记 | 唯一、一致、可选可解锁 | 人工核对 |
+| 推理质量 | 关闭提示仍可人解，关键选择有依据 | 人工推理与试玩 |
+| 教学 | 1-4 前理解基础操作与大格计步；1-7 出现先观察再画 | 新玩家试玩 |
+| 操作与提示 | 可恢复错误，提示考虑全部条件，窄屏可读可画 | 手机试玩 |
+
+建议找 3–5 位未接触玩法的玩家，记录思考时长、首次错误位置、回退次数、提示使用和口述推理。用这些记录修正关序；不要把自动评分当作实测结论。
+
+## 9. 六边一笔的独立规范
+
+共享“每格一次、数字对应步号、完整解唯一、允许改错”的目标，但不共享矩形拼块规则。
+
+| 项目 | 六边玩法要求 |
+|---|---|
+| 几何 | 正六边形，轴坐标 `q/r`，六向共边；没有矩形大格与奇偶条件 |
+| 墙 | 放在两格真实共边上，封住该边，不占据一格 |
+| 墙有效性 | 教学包第 3 关起、后续包全部关，至少一堵静态墙或转墙；去掉全部墙后不再唯一 |
+| 静态墙冗余 | 设计上应去除；当前 validate 只报告“可删墙”，不会据此判失败 |
+| 转墙 | 实验机制：每落一格（含起手）顺时针转 120°；用出发前墙位判断通行，落格后再转；撤销恢复相位 |
+| 转墙必要性 | 删除任意转墙后不再唯一，且任意候选边上的静态墙都不能替代它维持唯一；validate 强制检查 |
+| 容错差异 | 当前六边玩法沿路退到上一格；不具备数字玩法点任意历史格一次截断的操作 |
+| 当前内容 | 教学 10 关＋转墙实验 9 关；最多 4 个转墙只是当前实验规模，非正式内容上限 |
+
+不要将 README 的“无冗余墙”描述误写成所有静态墙都已被自动校验器强制验收。转墙规则需要独立排关和试玩，不直接套用数字玩法的线索间隔评分。
+
+## 10. 本次核对与来源
+
+2026-10-12 重新执行工程现有 `tools/validate.ts`：数字玩法 **26/26** 通过；六边玩法 **19/19** 通过。数字关所有奇偶条件通过逐条删除检查；六边校验未报告可删静态墙。
+
+环境缺少本地 `tsx`，标准 `npm run validate` 因依赖缺失无法启动；本次使用 Node 24 的 TypeScript 支持及临时的扩展名解析钩子直接加载原校验器，无修改工程代码。此结果仅代表关卡自动校验，不代表本次完成了完整 `npm run check` 或真人试玩。
+
+主要依据：
+
+- [产品结构](PRODUCT.md)与[仓库说明](../README.md)：玩法边界、当前内容量。
+- [数字玩法 GDD](../modes/01-number-stroke/docs/GDD.md)及[玩法说明](../modes/01-number-stroke/README.md)：目标、教学与内容原则。
+- [数据类型](../modes/01-number-stroke/src/types.ts)、[盘面](../modes/01-number-stroke/src/board.ts)、[对局规则](../modes/01-number-stroke/src/game.ts)：当前硬规则。
+- [生成器](../modes/01-number-stroke/tools/generate.ts)、[设计工具](../modes/01-number-stroke/tools/design.ts)、[发布校验](../modes/01-number-stroke/tools/validate.ts)：实际制作与验收能力。
+- [六边 GDD](../modes/03-hex-walls/docs/GDD.md)及[六边发布校验](../modes/03-hex-walls/tools/validate.ts)：墙与转墙差异。
+
+如以后扩展机制或包结构，应先更新对应玩法规则与验证能力，再同步本文。