docs: 三文档完整更新至 0.1.21

AGENTS.md：架构章节重写（0.1.14 大重构路径）+ 引擎红线（时轮/随机/事件闸/特效出口/插件/门面/双金钟罩） + 世界自演进模型 + sqlark陷阱 + 数值基调（0.1.16 修为经济化/0.1.17 市场实体化）+ 修改纪律 README.md：快速开始（1018 用例）+ 0.1.14+ 架构一览 + 守护机制（双金钟罩/事件闸/插件/回放） + 版本沿革 0.1.12-0.1.21 PROJECT_MEMORY.md：版本时间线补齐（0.1.12-0.1.21 每迭代的为什么）+ 关键架构决策（事件闸定稿/WorldSim 四层递进/引擎表现双通道/normalize即迁移/线程定论） + 踩坑教训（era 无延续档/潮汐符号反向/事件闸竞态/每tick存档/金钟罩盲区） + 诚实技术债清单 + 修改路径
2026-08-23 15:26:48 +08:00
parent 10ed1e7d9b
commit 8f9c3c9a72
3 changed files with 144 additions and 102 deletions
@@ -4,6 +4,7 @@

 一座庄园、一家修士、四邻势力，随年月流转：族人修炼突破、建筑产出、探秘寻宝、婚丧嫁娶；
 仇家犯境则结阵应战；百年之际，望气定鼎，春秋原上写下一卷族史。
+**世界也在自演进**：市场有真库存与供需呼吸，NPC 有战略姿态与恩怨网，时代有盛世乱世的大势流转——天下兴衰与家族命运互为因果。

 ## 快速开始

@@ -11,32 +12,39 @@
 npm install                # 依赖（含 git.metona.cn 私有 registry，token 在用户级 ~/.npmrc）
 npm install-scripts approve electron esbuild   # npm12 首装时必须（Electron 二进制）
 npm run dev                # 开发模式（热更新）
-npm run verify             # 发布验收哨兵：vitest + typecheck + build
-npm run verify:package     # 附打包预览（electron-builder）
-npm run package            # 直接打包（Windows 需在 Windows 侧执行）
-npm test                   # 仅测试（923+ 用例）
+npm test                   # 引擎测试（43 套件 / 1018 用例，纯 Node 无 GUI）
+npm run build              # 产物到 out/
+npm run package            # 打包（Windows 需在 Windows 侧执行）
 ```

+端到端冒烟（渲染 + OPFS + 开局推进 + 可选截图）：见 `AGENTS.md`「命令」。
+
 ## 架构一览

 ```
-src/renderer/game/            纯 TS 引擎（无 React/DOM，可被 vitest 直测）
-  core/        rng(RngHub) · clock(GameClock·7相位) · plugin · legacy · report · yearaxis · biography · genealogy
-  data/        balance 表 + DataPackRegistry（数据包可覆写）
-  engine/      world · clocks(注册) · pluginManager(∃插件管线) · capabilities(12 能力卡) · api(GameFacade act/query/subscribe/about)
-               systems/(生产·寿元·修炼·任务·事件·外交·婚育·渡劫·大比·寄读)
-  storage/     db(MetonaSqlark 单例) · slots(存档槽+快照) · migrate(版本迁移链 v1→v2)
-src/renderer/ui/              React + zustand（store 持 GameFacade；面板订阅 revision 刷新）
-src/main/                     Electron 主进程（app:// 协议 + IPC 存档导出/导入）
+src/renderer/game/                纯 TS 引擎（无 React/DOM，vitest 直测；单线程，实测 0.05ms/tick）
+  engine/GameEngine.ts            唯一门面：advance / restore / engineFromSnapshot / about / resolvePending
+  engine/kernel/                  Kernel（Clock+Rng 三合一）+ clock / rng(RngHub) / plugin / guide / urgency...
+  engine/runtime/                 World（大对象+normalize+bus 转发）· clocks（时轮注册）· ApiFacade（GameFacade）
+                                  Systems/（生产/修炼/任务/事件/外交/婚育/渡劫/大比/寿元/战斗）
+                                  capabilities（12 能力卡）· pluginManager（插件管线）
+  engine/sim/                     WorldSim（世界自进化）· worldsim-data（数值唯一权威）· Market（行情/买卖）
+  engine/narrative/               族谱/传记/定鼎/年轴/百年报告
+  data/                           balance 表 + DataPackRegistry（PILL_RECIPES / FORGE_RECIPES / ERA_CONF）
+  storage/                        db(MetonaSqlark 单例) · slots(槽+快照) · migrate(CURRENT_SCHEMA=2，normalize 即迁移)
+  types/domain.ts                 全量领域类型（改状态结构先看它）
+src/renderer/ui/                  React + zustand（store.ts 主状态；面板按 tab 挂载；LogFeed 精订阅）
+src/main/                         Electron 主进程（app:// 协议 + IPC 存档导出/导入）
 ```

-设计文档见 `AGENTS.md`（环境坑/架构红线/方言陷阱/金钟罩约定）。
+设计文档见 `AGENTS.md`（环境坑 / 架构红线 / 引擎纪律 / 金钟罩双基线 / 修改纪律）。

 ## 守护机制

- **金钟罩**：tests/clock.test.ts 三枚固定 seed × 560 月指纹常驻（0.1.8 基线：9af71ecb/63cede89/ebfec4a4）；有意变更时序需受控更新并注明。
- **插件化**：万物皆是插件（系统/数据包/事件池），示例见 tests/helpers/examplePlugin.ts。
- **可回放**：种子随机（sfc32）+ 闰档快照 + 回档时间轴。
+- **双金钟罩**：`tests/clock.test.ts` 的 `GOLDEN`（直调冻结世界）+ `GOLDEN_RESOLVED`（自动 resolve 长跑"现实"世界），各 3 固定 seed × 560/1200/2160 月（47/100/180 年）= 18 指纹；指纹含全世界轴（era/stance/prosperity/关系网/事件闸）；**0.1.21 基线**。有意变更时序需受控更新并注明。
+- **事件闸**：pending 唯一入口 `fire(w,id,priority)`——高优（raid/渡劫/大比）可顶替被占者，被顶替者入队下月兑现；`applyEventChoice` 前置校验防陈旧 Modal 二次结算。
+- **插件化**：万物皆是插件（系统/数据包/事件池），三核心插件 protected 常驻；示例见 tests/helpers/examplePlugin.ts。
+- **可回放**：种子随机（sfc32，引擎域零 Math.random）+ 快照回放保真（restore 重建内核+回置 rng）。

 ## 打包产物

@@ -44,19 +52,20 @@ src/main/                     Electron 主进程（app:// 协议 + IPC 存档导
 - 图标资源 resources/icon.png|ico —— electron-builder 自动使用
 - 注意：WSL/Linux 交叉打 win 包可行但未签名，正规发布请用 Windows 侧重跑

-## 版本沿革（0.1.0 → 0.1.9）
+## 版本沿革（0.1.0 → 0.1.21）

 | 版本 | 主题 |
 |---|---|
-| 0.1.0 | 核心循环（修仙/家族/经营/战斗）完备可玩 |
-| 0.1.1 | 养成闭环+回档+叙事（指婚/装备/祭祖/战报匣/年度纸笺） |
-| 0.1.2 | 宗族气韵（职事/悟道/谱系/碑录/庆典/飞升/合音效） |
-| 0.1.3 | 深度审计（旧档兼容/血缘/联姻/远征修复） |
-| 0.1.4 | 百年定局（终局/大比/寄读/春秋原） |
-| 0.1.5 | 人物志（志向/渡劫/列传/契合/回声） |
-| 0.1.6 | 时轮与造化（GameClock/RngHub/时节/年轴/保护） |
-| 0.1.7 | 仙门之钥（门面/能力注册表/数据包/开发者面板） |
-| 0.1.8 | 万物皆是插件 + 全应用审计（60+ 缺陷歼灭） |
-| 0.1.9 | 百年报告 + 存档迁移 v2 + 战斗阵型 + 冬祷 + 发布哨兵 |
-| 0.1.10 | 长线决断（数值重建：修炼提速/寿元放宽/渡劫修复 + 拍卖/传薪/护族） |
-| 0.1.11 | 全源码审计缺陷歼灭 + UX 打磨（警讯徽章/首启引导/格式化） |
+| 0.1.0-0.1.11 | 核心循环 → 插件架构 → 审计三连（详见 docs/PROJECT_MEMORY.md） |
+| 0.1.12 | 金碧山河（SVG 素材 + 动效系统 + 舞美重装） |
+| 0.1.13 | 交付与回档（工艺/界面修复 + UI 存储直连回档） |
+| 0.1.14 | 大重构：GameEngine 门面 + Kernel 三合一 + WorldSim 世界自进化（五大闭环） |
+| 0.1.15 | 深度审计加固（7 P0 + 20+ P1 歼灭；restore 双注册/引擎锁死等） |
+| 0.1.16 | 资源闭环 × 世情入味（修为耗草/炼丹概率化/铸器/灵脉收益/NPC 战力/灾变落效） |
+| 0.1.17 | 天下为市——市场实体化（真库存/供需呼吸/NPC 上桌/玩家回写）+ 战争伤骨 + 关系网 |
+| 0.1.18 | 时代绘卷（世纪弧 era/NPC 景气/蝴蝶效应/十年鉴）+ 特效入引擎（onFx 语义出口） |
+| 0.1.19 | 八方风雨（NPC 战略姿态/超卖潮/盟约连坐/干预天下）+ 孤立系统归并（FxGate/音效/兜底） |
+| 0.1.20 | 万世无谬（第二轮全量审计：事件闸优先级/era 延续/潮汐符号/弱锚定/双金钟罩） |
+| 0.1.21 | 大势流转（线程定论 0.05ms、era↔景气双向闭环、世界史表、渲染管线修复） |
+
+详见：`docs/PROJECT_MEMORY.md`（设计哲学与每个迭代的"为什么"）。