type
Post
status
Published
date
Jul 15, 2026
slug
article-02-rewrite
summary
从继续冒险、稳定题目和不丢进度这些日常体验出发,理解方寸专注的本地优先架构。
tags
本地优先
浏览器存档
儿童应用
category
技术分享
icon
password
系列导航:上一篇 · 下一篇
孩子玩到一半关掉页面,下一次打开还能接着玩;刚才抽到的故事和题目不会忽然换掉;一次游戏结束后,成绩能进入记录、掌握度和冒险进度。对使用者来说,这些是很自然的期待。
“方寸专注”的技术安排,正是围绕这些期待做的。它没有后端服务、网址路由库、外部状态管理工具,也没有 TypeScript;运行时只依赖 React、React DOM 和 Lucide 图标,Vite 负责构建。重点不是追求“零依赖”,而是让一段本地单人冒险在中断、升级和新增玩法后仍然可靠。
先用一句话概括:**孩子点按钮,界面负责把动作交出去;规则负责算出下一步;`App` 负责把值得记住的结果保存下来。**
先看体验,再看分工
下面这张图不要求先认识所有技术名词。可以把它当作一间小剧场:内容准备好剧本和题目,规则决定剧情如何向前,界面把它们呈现出来,存档则替孩子记住上次停在哪里。
源码目录有意保持扁平:22 个 JavaScript/JSX 文件和一个全局样式文件,已经足以看清每件事归谁负责。项目没有为了显得复杂,预先拆出 `components/`、`hooks/`、`services/` 或 `stores/` 目录。
这件事 | 由谁负责 |
顶层页面切换、设置、保存、训练完成 | `App.jsx` |
冒险画面和故事呈现 | `Adventure.jsx` |
七种游戏的互动 | `Games.jsx` |
创建冒险、处理动作、最终结算 | `adventure.js` |
卷灵、天气、地脉、百工和试炼规则 | `adventureStrategy.js` |
主线、事件、伴灵记忆的选择与轮换 | `adventureStory.js` |
存档整理、难度适配、题目和地图生成 | `training.js` |
网页音频节点与播放安排 | `ambientAudio.js` |
场景、题库、游戏和故事的静态资料 | 各 `*Content.js` / `gameConfig.js` |
这里有一条特别重要的约定:**界面不私自决定游戏结果。**按钮只提交“做了什么”,规则函数决定“接下来怎样”;每个游戏完成后上报完整成绩,`App` 再把成绩写入训练记录、掌握度和冒险历史。这样,孩子在不同页面玩到的结果,都会进入同一本“成长记录”。
`App` 像总台,不像规则书
这个应用不使用 URL 路由,而是在 `App` 里用一个简单的 `screen` 状态,在首页、冒险、练习册、游戏、结算和记录页之间切换。
这不适合需要把某一篇内容链接分享给别人、并直接打开指定页面的网站;但对一个在本机独自游玩的体验很合适。切换画面不应该绕开正在保存的冒险。
`App` 主要做四件事:
- 开始时读出浏览器里保存的进度,并把它整理成当前可用的样子。
- 按当前页面和所在的卷,选择环境音乐主题。
- 把界面传来的操作交给规则函数处理,并保存更新后的进行中冒险。
- 一局结束时,统一更新本次记录、掌握度、旅程和冒险信息。
无论是自由练习还是冒险中的练习,最后都会走同一条路:
这里的“浏览器本地存档”指 `localStorage`:它是浏览器提供的一小块持久空间,网页可以把少量文字形式的数据放进去;关闭页面、再次打开时,数据还在。组件不会直接往这里写。这样,默认值、旧存档升级和异常数据处理都集中在一个入口,不会散落在不同游戏里。
一程冒险,是一份能装进存档的行程单
“状态机”听起来像工程术语,其实可以理解为一张有规则的行程单:现在处在哪一站,允许做什么;做完以后,下一站去哪里。它不会让“还在看剧情”时误结算游戏,也不会让不属于本程的成绩混进来。
一程冒险在程序里叫作一个 `run`。它不是几组零散的“显示/隐藏”开关,而是一份完整记录:场景、随机种子、任务、伴灵、策略、故事计划、故事游标、已完成的遭遇和开始时间。
这份记录能原样转成 JSON,也就是一种通用的文字数据格式,放进存档。因此刷新页面后,应用恢复的是已经选定的故事、游戏顺序和随机种子,而不是根据此刻的进度重新猜“刚才大概玩到哪儿”。
真正负责转站的,是 `adventureReducer(run, action)`。`reducer` 可以把它理解为“按规则改写行程单的总表”:给它当前行程和一个动作,它只返回下一份行程,不直接碰界面或存档。它先检查当前 `stage`(阶段);不合时宜的动作会原样返回。例如,只有在 `encounter` 阶段,且成绩里的 `game` 与计划中的游戏一致时,`complete-encounter` 才会被接受。
完成一次遭遇后,规则会追加成绩、移动故事游标,再决定回到剧情、插入卷内事件,还是进入奖励页。所谓“纯函数”,意思是它只根据给它的输入得出输出,不偷偷读取或修改别处的数据。这样同一份行程和同一个动作,总能得到同样的下一步,也更容易检查对不对。
“随机”可以变化,也可以不失忆
冒险要有新鲜感,题目和顺序会变化;但正在玩的这一程不能因为刷新页面就换一副牌。这里采用的是“有种子的随机”:创建 `run` 时,种子由日期、已完成场景数和历史长度派生;如果测试时指定同一个种子,也会得到同一个结果。
“确定性”并不表示内容永远不变,而是表示**相同输入会得到相同输出**。可以把种子想成一张抽签号码:号码相同,抽到的顺序就相同;号码换了,顺序才可能换。
`seededShuffle` 用一个很小的线性同余生成器配合 Fisher-Yates 洗牌完成这个过程。它不用于密码或安全保护,但很适合这里:题目有变化,刷新后却不会突然变成另一套题。
因此,所有会影响继续游玩的选择,都会在创建 `run` 时写清楚:
- 本程的三个或四个游戏,以及它们的顺序。
- 每个遭遇的 `seed`、`variant` 和 `ruleSet`。
- 委托和待发现物。
- 当前伴灵,以及“藏锋”复制的是哪一种效果。
- 主线、事件或记忆内容的 ID。
界面在每次重新显示时不会再抽签。这也让检查标准很明确:相同种子必须得到深度相等的结果;相邻种子应该得到不同排列;进行中的 `run` 经过 `normalizeProgress` 整理后,计划不能被重新排序。
本地存档最难的部分,是让旧进度安全回来
本地优先并不等于把一个对象随手塞进浏览器。`localStorage` 是这个应用唯一会接收外来数据的入口:旧版本留下的数据、被手工改过的数据,以及没有完整写完的数据,都可能从这里回来。
所以,应用会先“归一化”存档:把它检查、补全并整理成现在版本真正能用的格式。当前进度有两条相互独立的版本线:
- `adventure.progressionVersion: 2`:记录场景级的 24 步进度。
- `adventure.story.storyVersion: 2`:记录七种游戏的轮换和故事记录格式。
两条版本线分开,是为了避免不必要的改动。故事结构升级,不该重新换算 `completedRuns`;玩法轮换升级,也不该重建一程已经开始的冒险。
第一次迁移最容易出错的地方,是旧版本把每个场景拆成三阶段。普通旧存档可以用 `ceil(old / 3)`,也就是“除以三后向上取整”,为已经开始恢复的场景记一份完成;但如果存档里有一程尚未结束、且不是重玩的冒险,则要用 `floor(old / 3)`,也就是“除以三后向下取整”。否则,那一程完成时会多推进一次。
迁移结束后会写入版本号。第二次再整理同一份存档,结果必须保持不变;这就是“幂等”,即重复做一次不会再产生额外变化。
系统还会过滤未知场景、过期故事 ID、重复发现物和错误伴灵;数组有明确上限。进行中的 `run` 如果没有 `storyPlan`,则保留旧的 reducer 路径,让老玩家先安全完成这一程。
七种游戏,交的是同一份成绩单
新增游戏时,最容易发生的麻烦是每个玩法各自计算分数、各自写记录。这样一来,记录页和难度推荐会越改越复杂。
“方寸专注”让七种游戏最终都交回同一种结果:
公共的 `makeResult` 根据正确量、错误量和目标时间计算准确率、星数和分数:
`detail` 和 `items` 可以记录某种玩法特有的信息,但不会改变后续系统读取成绩的方式。因此“画中寻物”加入后,记录页、自适应难度、冒险结算和掌握度系统不需要懂它每一个按钮;它们只需要理解这份统一的 `result`。
这也是这套架构会继续保留的原因:界面可以换,玩法可以增加,完成后的成绩格式不能跟着漂移。
为什么目前不用 TypeScript 或状态库
项目当然可以迁移到 TypeScript;但它此刻最需要的,不是更多静态注解,而是把运行时的边界处理正确。浏览器里留下的旧 JSON,不会因为源码有类型就自动可信;动态内容目录也不会因为写了 `as StoryPlan` 就保证引用一定存在。
现在的做法,用构造函数、归一化函数、受限 ID、阶段检查和 72 项纯逻辑测试来表达这些约定。对 22 个 JavaScript/JSX 文件来说,这样的成本更合适。
同样地,冒险状态已由一个 reducer 管理,顶层状态仍然能在 `App` 中清楚读到。此时引入 Redux 或另一套 store,只会多出第二个需要保存的边界。等到项目需要账号、多儿童档案、跨设备同步,或能用链接直达指定页面时,才真正到了下一次架构升级的时机。
这也说明了本地优先的边界:清空浏览器数据会丢失记录;不同设备之间不会同步;一个浏览器只有一个儿童档案。这些是明确接受的产品限制,并不是“纯前端”几个字可以掩盖的问题。
下一篇会进入七种游戏如何共用这套底座:调度器怎样让连续三程覆盖全部玩法,故事选择又如何留下短暂回声,同时不把孩子困在错误分支里。
- 作者:Leisurelywolf
- 链接:https://blog.869669.xyz//technology/article-02-rewrite
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议,转载请注明出处。






