NumberSwipe_New/wechat-campaign-200-r2/HANDOFF.md

# NumberSwipe 主程交接

更新时间：2026-10-20（北京时间）。面向接任主程；先读本文件、同目录 README.md，再查源码。当前任务已完成，没有正在等待执行的开发指令；下一步根据用户真机反馈继续调整。

## 1. 当前版本和目录

| 用途 | 目录或入口 |
| --- | --- |
| 本会话微信开发工作副本 | `G:\项目\NumberSwipe\wechat-campaign-200-r2` |
| 已同步的微信项目副本 | `G:\项目\NumberSwipe-Variants\wechat-campaign-200-r2` |
| 200关评分修订版网页源项目 | `G:\项目\NumberSwipe-Variants\campaign-200-r2` |
| 微信导入入口 | 微信项目中的 `project.config.json`，运行产物为 `game.js` |
| 网页试玩入口 | `G:\项目\NumberSwipe-Variants\campaign-200-r2\index.html` |
| 旧版，避免误改 | `NumberSwipe-Variants\campaign-200`、`campaign-50`（实际53关） |

两个微信目录不是自动同步关系。本会话在 NumberSwipe 下的微信子项目修改、验证后，再复制指定修改文件到 Variants 对应目录。继续开发前对比两边的源码和时间，避免覆盖其他会话的新改动。原 NumberSwipe 其他模式、旧网页 DEMO 不在本次修改范围。

微信版关卡来源：`scored-2026-10-15-r2`，200关、20章，每章10关。微信适配版本标记：`2026-10-19-animated-lessons-one-second`。不得从同级 `wechat` 或其他模式的微信目录混入关卡。

本次交接核对时，两边 `game.js` 及下述最新压缩包内的 `game.js` SHA-256 相同：

```text
4069ac9b0f38d42196a544f008988808c227653abb0bdb8e326aa7adcfb861a5
```

这只是交接时点的快照；之后有新改动时应重新核对。

## 2. 最新交付与用户要求

最新微信包：

`G:\项目\NumberSwipe-Variants\releases\NumberSwipe-campaign-200-r2-高亮指路-保留玩家填色-20261020.zip`

同名副本也在 `G:\项目\NumberSwipe\releases`。更早的“动画教学”包较慢，不能当最新版。压缩包已经构建，导入微信开发者工具后重新编译并生成真机预览；旧二维码可能加载旧代码。本会话未上传或发布小游戏。

最新两项用户要求已实施：

1. 新机制说明必须使用真实游戏关卡画面，文案与动画联合解释，不再只有文字。
2. 用户认为逐格停顿效率低，要求整段约1秒、连续流畅；当前 `duration:1000` 指整段，不是每格1秒。结束停留，点击“重播”再播放。

不要恢复此前每拍1300毫秒、移动450毫秒后停顿的实现，也不要未经用户要求放慢动画。错误反馈和门状态变化仍保留；是否足够看清需真机反馈。

目录里还包含通关操作栏修订：完成后底部由“下一关”独占，替换重开/撤销/指路；最后一关为“返回选关”。反馈、操作栏与棋盘分区，出现按钮不能挪动或遮盖棋盘。该修订见当前源码、README 和 validation，不要用旧文件覆盖。

## 3. 源码定位及修改方式

| 文件 | 职责 |
| --- | --- |
| `src/main.mjs` | 微信 Canvas 页面、触摸路由、规则面板、演示布局、动画绘制、前后台处理 |
| `src/copy.mjs` | 最新十类教学及组合规则文案；保留具体动作、奇偶例子，不退回旧网页术语 |
| `src/hints.mjs` | 分段提示判定、生命周期和独立透明层光效 |
| `src/lessons.mjs` | 按当前机制选择真实教学关、通过求解器取得演示路线、错误例子、回退、1秒时间轴 |
| `src/platform.mjs` | wx 到上游 UI 所需接口的适配、PACK、存储和 Canvas |
| `src/audio.mjs` | 微信原生音频播放器，静音、后台停止、试听及错误诊断 |
| `audio-assets.mjs` | 生成本地 WAV 资源 |
| `build.mjs` | esbuild 打包，注入微信适配及演示绘制接口 |
| `src/upstream/*` | 网页 r2 的四个原始快照；来源及哈希见 source-manifest.json |

保持 `src/upstream/levels.json`、`rules.mjs`、`ui.mjs`、`audio.mjs` 快照原样。微信改动放适配层，必要的上游 UI 替换通过 build.mjs 注入；不要手工修改压缩后的 game.js。

教学实现细节：

- 共十类：基础、墙、横通道、竖通道、拐角、双色、奇偶、节奏门、六边形、无起点。
- 首次教学及手动规则页都使用实际教学关。组合关按出现的机制拆段，不展示当前正式关的完整答案。
- 演示复用上游盘面绘制；build.mjs 导出 `renderLesson`，暂存并恢复绘制状态，用独立 Canvas 输出。`previewOnly` 阻止教学绘制更新实际游戏 UI、报错、操作按钮等。
- 墙/同色显示红色阻挡线，方向/奇偶显示错误及回退。门展示切换、穿过保持开启、撤销穿门。
- `lessonFrame` 使用连续进度，main.mjs 绘制移动光圈和连接段；结束保持结果。翻段/重播重新计时；后台停止绘制，返回重新演示。
- 不修改玩家路线、存档、提示次数、音效记录；不要为了教学调用实际玩家输入函数。
- 只读诊断：`GameGlobal.numberSwipeR2.snapshot()`、`.buttons()`。可查真实游戏状态、音频状态及当前教学。

## 4. 已确认的玩法与表现约束

- 每格仅走一次，共边移动、不可斜走；固定数字表示第几步到达。无计时、体力和分数。
- 松手续画。拖动时只有回到紧邻的上一格才撤销一步，碰其他已走格不撤销；撤销按钮退一步，重开清空。
- 方向格是明确的通道：lr 横向、du 纵向，ru/dr/dl/lu 指定两侧拐角，可反向通过，不能作为端点。图标居中固定，线从图标穿过，正确亮起、错误变红，均不位移。
- 双色仅用蓝/橙区分，连续两格必须异色。不要恢复三角/圆形叠加标识；内部 category 名字仍可能为 circle/triangle，不等于需要画形状。
- 大格/异形整块一步，不画内部拼接缝；双色、奇偶不要求必须带大格。
- 奇偶按访问步数判定。避免同一格叠加奇偶和方向图标。
- 永久墙不能通过。节奏门空盘关闭，起点算一步，每进入一格切换一次；移动前检查门状态。合法穿过后保持开启，撤销穿门那一步后恢复切换，重开重置。
- 六边形共边六邻接，可以混合其他已支持机制；关卡应宽向展开，避免全部是纵向蛇形单路线。
- 指路现为高对比分段提示（白色/深色双描边与流动光点），只展示最早未完成的一段。节点为起点、数字点、方向点、奇偶点、终点，按正确解排序；正确到达段末后消失，再点才提示下一段。暂不接广告。提示使用独立透明 hintCanvas，清空或擦除只影响提示层；已走格多边形和实际连接段让出给原棋盘，保留整格填色及数字、方向反馈。不要在主 Canvas 上使用 destination-out 清除玩家绘制。
- 不恢复已被用户否决的相对步差、先后链、到达窗口、开关钥匙开门。保留的是永久墙和节奏门。
- 玩法可以混合，但新机制首次出现需极简教学；用户不需要专门的大格教学。
- 沿用原项目白底、紫色路线及既有 UI；不要重新发明一套皮肤。

音效：普通移动沿当前音色每步升一个半音；撤销/重开后步数决定音高。其他五类反馈音保持既有听感。微信使用随包41个 WAV（36个移动音＋五类反馈）及 `wx.createInnerAudioContext`，不依赖浏览器振荡器。静音/进入后台时停止播放和延迟音效。

## 5. 构建、测试与实际验证边界

在当前微信项目目录执行：

```powershell
Set-Location 'G:\项目\NumberSwipe\wechat-campaign-200-r2'
node build.mjs
node --test hints.test.mjs lessons.test.mjs audio-copy.test.mjs
node smoke.mjs
```

本机 Node：`C:\Program Files\nodejs\node.exe`。build.mjs 当前硬编码 esbuild 位置为 `G:/项目/NumberSwipe/modes/01-number-stroke/node_modules/esbuild/lib/main.js`，迁移电脑需调整依赖路径。播放器无第三方运行时依赖。

已报告通过：

- lessons.test.mjs：12项，包括十类教学、200关机制映射及1秒连续时间轴/结束停留。
- audio-copy.test.mjs：6项，原生音频、静音/后台、音高、资源和文案。
- smoke.mjs：实际 game.js 在模拟 wx/Canvas 中的200关唯一解、触摸通关、撤销/重开/提示、存档和前后台；教学状态隔离与窄屏分页。
- 当前 validation.json 另记录通关按钮布局及4种手机尺寸检查。该内容可能来自其他会话的更新，以当前文件为准。

不要把 Node 模拟器、假 Canvas 和边界断言当作真实屏幕截图或真机验收。本会话未验证手机实际帧率、1秒内的错误提示可读性、真实字体布局及音效听感；需要开发者工具和手机预览确认。文档交接本身未重新运行全套游戏测试。

smoke.mjs 会校验上游路径和快照哈希，并覆写 validation.json。移到新机器时缺少上游目录会导致来源检查失败，不能直接删除该检查掩盖问题。

## 6. 长线关卡设计背景（调整关卡时才需展开）

用户反馈原200关重复、后半程太简单、最大18格、六边形多为单调竖向路径。r2 是评分后重排并重制的版本，最大36格，不能误把旧200关当当前数据。评分仅是推理负担代理，不能当真人难度或通关率。

用户主观锚点对应旧版编号：

- 需要提示/否则思考很久：73、76、77、80、85、88、144。
- 略难、应在100关以后经常出现：149、158；比需要提示简单明显。
- 喜欢但不能过多：无固定起点的111（12-1）、136（14-6）。此前端口17851/17581口述有歧义，用户明确确认关卡号码和无起点特征；不要据端口推翻反馈。

r2 无起点关序号为45、65、105、145、185。网页设计资料、评分表、关卡映射及作者证明在 `campaign-200-r2` 的 DESIGN/SCORES/DIFFICULTY 页面、design.json 和 reports 下。作者解不应打包给玩家；运行判定用规则求解。

此前局域网约定：17850=53关，17851=旧200关，17852=r2评分修订200关。服务可能已停止或换址，先查实际监听和返回版本，不能凭端口断言当前内容。微信包与这些网页服务相互独立。

## 7. 接手时的行动顺序与注意事项

1. 确认用户在修改微信版还是网页版，阅读本文件及当前 README，核对两个微信目录是否仍一致。
2. 读取当前源码及 Git 状态；原工作区存在其他会话未提交文件，不清理、不回滚。用户已授权的范围内直接完成工作，不重复请求确认。
3. 若继续调教学，先看 lessons.mjs/main.mjs/copy.mjs，再看 build.mjs 的 renderLesson 注入。保持上游快照、200关排列和存档键 `variant:campaign-200-r2:v1`。
4. 修改后构建和运行与改动相关的检查，再同步微信副本、生成带新版本名的独立包。不要默认两个目录有自动镜像。
5. 本环境 Variants 目录不在默认可写根内，写入需通过工具申请 require_escalated；读取允许。不要绕过权限。

当前 package.ps1 可生成仅含运行必需文件的独立导入包。重新打包时需明确包含 game.js/game.json/project.config.json/audio 和所需开发文件，排除作者解、研究资料及无关项目；按 project.config.json 的上传忽略配置复核资源。上传发布前沿用用户当前授权范围，不假定本交接授予上传授权。

给新会话的起始消息可直接用：

> 请接任 NumberSwipe 主程，先读取 G:\项目\NumberSwipe\wechat-campaign-200-r2\HANDOFF.md 和同目录 README.md，核对当前文件及另一个微信副本后，再按我的新需求继续。不要覆盖其他会话更新，也不要重新生成或打乱当前200关。