docs: 三文档同步至 0.1.26
AGENTS.md：金钟罩注释修正（0.1.21→0.1.24 基线，25/26 零漂注明）+ MOD 红线小节 + 架构树补 worldgen/modSchema/modManager + 世界模型补（灾因聚合/家族生灭/世界种子） + 测试数 47/1047 README.md：版本沿革补 0.1.22-0.1.26（灯下春秋/生灭千秋/寰宇初构/乾坤一统/墨规清辉） + MOD_GUIDE 链接 PROJECT_MEMORY.md：时间线补 5 个迭代「为什么」+ 新决策（世界种子独立 rng/MOD=插件一等子类/ 落档则永稳纪律）+ 坑教训两条（生成必落档/聚合默认零漂）+ 技术债补 3 条 + 修改路径更新
This commit is contained in:
@@ -41,8 +41,8 @@ src/renderer/game/ 纯 TS 引擎（无 React/DOM，vitest 直
|
||||
engine/kernel/ Kernel.ts（三合一：Clock+Rng+BUS 转发）+ clock/rng/plugin/names/format/guide/urgency/timesense
|
||||
engine/runtime/ World.ts（大对象+normalize+bus 转发）/clocks.ts（时轮注册）/ApiFacade.ts（GameFacade）
|
||||
Systems/（production/aging/cultivation/missions/events/diplomacy/marriage/tribulation/tournament/lifecycle/combat）
|
||||
capabilities.ts（12 能力卡）/pluginManager.ts/plugin-bootstrap.ts/creation.ts/pcgen.ts
|
||||
engine/sim/ 世界自进化： WorldSim.ts / worldsim-data.ts（数值与常量唯一权威）/Market.ts / worldsim-brief.ts
|
||||
capabilities.ts（12 能力卡）/pluginManager.ts/plugin-bootstrap.ts/modSchema.ts（MOD 范式）/modManager.ts（MOD→插件）/creation.ts/pcgen.ts
|
||||
engine/sim/ 世界自进化： WorldSim.ts / worldsim-data.ts（数值与常量唯一权威）/worldgen.ts（世界种子生成器）/Market.ts / worldsim-brief.ts
|
||||
engine/narrative/ 族谱/传记/定鼎/年轴/百年报告
|
||||
data/ balance 表 + DataPackRegistry（registry.ts pack() 单源；PILL_RECIPES/FORGE_RECIPES/ERA_CONF 等）
|
||||
storage/ db(MetonaSqlark 单例)/slots(槽+快照+exportEnvelope)/migrate(CURRENT_SCHEMA=2,即 normalize 即迁移)
|
||||
@@ -59,8 +59,9 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
|
||||
- **事件闸**：pending 事件唯一写入入口是 `events.ts` 的 `fire(w, id, priority)`（0=普通遇占放弃 / 1=高优 raid·渡劫·大比可顶替被占者，被顶替者入 `eventQueue` 下月兑现不丢失）。**禁止直写 `state.pendingEvent`**（渡劫/破境丹均已改走 fire）。`applyEventChoice` 前置校验 `pendingEvent===id`（陈旧 Modal 二次结算防线）。
|
||||
- **特效/音效语义出口**：`WorldEventBus.onFx?(em: FxEmit)` + `World.emitFx(kind, source?)`（零 rng 消耗）；UI 的 `makeBus` 桥接 FxGate；`onLog kind` 音效映射保留作兜底。
|
||||
- **插件架构**（0.1.8 起，路径已迁 engine/runtime|kernel）：`kernel/plugin.ts` 协议、`runtime/pluginManager.ts` 安装管线（依赖校验/异常回滚/追踪型上下文——注销时钩子全摘）、`plugin-bootstrap.ts` 三核心插件（core-systems/core-data/core-events protected）。事件多池 `world.eventPools`；**findEvent 必须带 world 参数查池**。能力卡 12 张经 `viaCap` 注册；tournament/tribulation/apprentice/season 四卡各自内部检查 `w.sysEnabled`（无独立钩子）。
|
||||
- **MOD 红线（0.1.26 规范）**：MOD 只含 JSON 零脚本（`docs/MOD_GUIDE.md`）；**禁止新增 rng 消耗**（全局随机序列）；不改核心时序（扩展走五口：事件池/模板/词库/灾因/配方）；`modPreflight`+`validateMod` 先行（id 冲突用 `findEvent` 权威检测）；MOD 只影响**新开档**世界（老档世界变形成档记录）；MOD 状态随 `state.plugins` 持久化（对应 `worldGen.npcs` 落档保证读档永稳）。
|
||||
- **门面**：`runtime/ApiFacade.ts` GameFacade（act 24 项/query 6 类/subscribe 退订协议/about）；**UI 面板事实走 world 直调**（act 为测试/自动化通道），`actDirect` 与 ACT_CATALOG 语义对齐（0.1.20 补齐全 24 项）；store 的 `facade` 必须在 openState/startNewGame 赋值。
|
||||
- **金钟罩（双基线）**：`tests/clock.test.ts` 的 `GOLDEN`（直调冻结世界）+ `GOLDEN_RESOLVED`（自动 resolve 长跑"现实"世界），各 3 seed × 三档月数（560/1200/2160）共 18 值。当前为 **0.1.21 基线**（0.1.22 纯 UI 修复未动引擎，基线不变；见注释）。指纹 `tests/fingerprint.helper.ts` 含全世界轴（era/stance/prosperity/relationsWithOthers/calamity/pendingEvent/eventQueue/worldAnnals）。**有意变更时序/数值时**：指纹一并重算并在注释注明原因。
|
||||
- **金钟罩（双基线）**：`tests/clock.test.ts` 的 `GOLDEN`（直调冻结世界）+ `GOLDEN_RESOLVED`（自动 resolve 长跑"现实"世界），各 3 seed × 三档月数（560/1200/2160）共 18 值。当前为 **0.1.24 基线**（0.1.25/0.1.26 世界生成默认池不变、灾因默认表不变 → 基线零漂，见注释）。指纹 `tests/fingerprint.helper.ts` 含全世界轴（era/stance/prosperity/relationsWithOthers/calamity/pendingEvent/eventQueue/worldAnnals/worldGen 摘要）。**有意变更时序/数值时**：指纹一并重算并在注释注明原因。
|
||||
|
||||
## 世界自演进模型（0.1.14 sim/ 层，改数值勿动流程）
|
||||
|
||||
@@ -68,6 +69,9 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
|
||||
- **世纪弧 era**：盛世/平世/乱世/末法，`ERA_CONF`（灾年概率/供需/拍卖/tideBias）+ `ERA_DURA`（续航窗口）；flow 权重和 <1（留白=延续档）；**转移权重受世界温度调制**（`worldTemperature()` + `tempEraK`）——时代由天下兴衰孕育、又重塑天下。
|
||||
- **NPC 定力**：`npcDyn.prosperity/stance/relationsWithOthers`——姿态（守成/扩张/隐忍/结盟）年首重估，调制 raid/互攻/贸量/外交；互攻按 power 加权 + 打残广播；玩家劫掠/结盟写关系网（蝴蝶效应）。
|
||||
- **灾年**：持续 6 月（`calamityLeft`），减产乘子（CALAMITY_FAMILY）+ 疫病/兽潮体感 + NPC 贸易 ×0.7 + 群雄相噬 ×1.5；世界侧 `CALAMITY_EFFECT` 冲击池。
|
||||
- **灾年** 补充：灾因注册表已聚合（`calamityNames/calamityFamilyOf/calamityEffectOf` + `addCalamity`——默认表不变，MOD/插件可注入灾因全链生效）。
|
||||
- **家族生灭**：`npcDyn.declineYears`（power<58 且 景气<38 连续 8 年）→ 覆灭（最强邻分食+史官广播）；家族数 < 开局目标（4~8）年首新贵补位（`greatNewbornChance`，乱世×2）。
|
||||
- **世界种子**（0.1.24）：`sim/worldgen.ts` `generateWorld(seed)`——NPC 4~8 家随机/初始关系网（1-2 世仇+1 盟友）/开局 era/市场 ±15% 偏移；**独立派生 rng**（`seed::worldgen`，World.rng 主序列零消耗）；`state.worldGen` 摘要落档（含 npcs defs——读档幂等重注册，存档世界永稳）。
|
||||
- **天下史表**：`worldSim.worldAnnals[]`（十年一鉴 80 页留档，免 newsFeed 裁剪丢失）。
|
||||
|
||||
## MetonaSqlark（@metona-team/metona-sqlark 0.7.4）陷阱
|
||||
@@ -100,6 +104,6 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
|
||||
5. **高危文件白名单**（world.ts / events.ts / store.ts / styles.css / cultivation.ts / **WorldSim.ts / worldsim-data.ts**）改动后必须 `git diff --stat` 核对改动面与预期一致。
|
||||
6. 每次迭代收尾：`git status` 应干净 + `git log --oneline` 确认每步都有提交记录；凡 "git stash/checkout/rm" 类命令，执行前后都 `git status` 留痕。
|
||||
|
||||
- 提交前：`npm test`（当前 43 套件 1018 例全绿）+ `npm run typecheck` 必须绿（改存储/SQL 后再跑一次冒烟）。
|
||||
- 提交前：`npm test`（当前 47 套件 1047 例全绿）+ `npm run typecheck` 必须绿（改存储/SQL 后再跑一次冒烟）。
|
||||
- 平衡数值集中在 `game/data/` 与 `engine/sim/worldsim-data.ts`（世界循环参数唯一权威），调平衡不改引擎流程。
|
||||
- 发布产物 `release/`、`out/` 均已 gitignore，勿入库。
|
||||
|
||||
@@ -37,7 +37,8 @@ src/renderer/ui/ React + zustand（store.ts 主状态；面板
|
||||
src/main/ Electron 主进程（app:// 协议 + IPC 存档导出/导入）
|
||||
```
|
||||
|
||||
设计文档见 `AGENTS.md`（环境坑 / 架构红线 / 引擎纪律 / 金钟罩双基线 / 修改纪律）。
|
||||
设计文档见 `AGENTS.md`（环境坑 / 架构红线 / 引擎纪律 / 金钟罩双基线 / 修改纪律）；
|
||||
**MOD 作者守则**见 `docs/MOD_GUIDE.md`（规范：命名/schema/五数据口/安全红线）。
|
||||
|
||||
## 守护机制
|
||||
|
||||
@@ -67,5 +68,10 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
|
||||
| 0.1.19 | 八方风雨（NPC 战略姿态/超卖潮/盟约连坐/干预天下）+ 孤立系统归并（FxGate/音效/兜底） |
|
||||
| 0.1.20 | 万世无谬（第二轮全量审计：事件闸优先级/era 延续/潮汐符号/弱锚定/双金钟罩） |
|
||||
| 0.1.21 | 大势流转（线程定论 0.05ms、era↔景气双向闭环、世界史表、渲染管线修复） |
|
||||
| 0.1.22 | 灯下春秋（Modal 全走 body Portal / 年报不打断自动速度 / 姓氏假功能修复） |
|
||||
| 0.1.23 | 生灭千秋（家族覆灭/新贵补位、秘境回池、WorldSnapshot、插件持久化/双闸/自动回滚） |
|
||||
| 0.1.24 | 寰宇初构（世界种子生成器：NPC 4~8 家随机/开局恩怨/era/市场偏移；插件的时轮锚点/模板注入） |
|
||||
| 0.1.25 | 乾坤一统（MOD 系统首版：userData/mods 扫描/解析/安装/持久化 + worldGen 存档永稳修复） |
|
||||
| 0.1.26 | 墨规清辉（MOD 规范范式：MOD_GUIDE/validateMod/灾因注册表 + 页面文本提亮可读性） |
|
||||
|
||||
详见：`docs/PROJECT_MEMORY.md`（设计哲学与每个迭代的"为什么"）。
|
||||
|
||||
+21
-3
@@ -35,6 +35,11 @@
|
||||
| 0.1.19 | 八方风雨 + 孤立归并 | NPC 从统计物理→行为战略（stance 四姿态）；超卖潮/盟约连坐/干预天下 |
|
||||
| 0.1.20 | 万世无谬 | 第二轮全量审计：**事件闸竞态**（raid 落地率 18%）/era 无延续档/潮汐符号反向——三处"看着合理其实错" |
|
||||
| 0.1.21 | 大势流转 | 线程定论（0.05ms 单线程无需 Worker）；era↔景气**双向闭环**（自演进最高形态）；渲染管线修 |
|
||||
| 0.1.22 | 灯下春秋 | 实拍双 bug：Modal 被 tabs z 层压制（Portal 根治）；年报打断自动速度；姓氏选择假功能 |
|
||||
| 0.1.23 | 生灭千秋 + 插件生态 | "世界会死人也会新生"（declineYears/覆灭/新贵）；插件从测试框架向真生态（持久化/双闸/回滚/公共面） |
|
||||
| 0.1.24 | 寰宇初构 | **世界种子生成器**：NPC 势力数量告别定死（4~8 家随机/开局恩怨/era/市场偏移）；插件时轮锚点+模板注入 |
|
||||
| 0.1.25 | 乾坤一统 | **MOD 系统首版**（MOD=插件一等子类，全 JSON 外部包）；修 0.1.24 遗留：worldGen 不含 npcs 落档（读档软瘫） |
|
||||
| 0.1.26 | 墨规清辉 | MOD **规范范式**（MOD_GUIDE/validateMod/权威冲突检测）；灾因归一化注册表（MOD 灾年入循环）；页面提亮（暗因：.dim 3.4:1 对比度） |
|
||||
|
||||
## 三、关键架构决策（及为什么）
|
||||
|
||||
@@ -62,7 +67,12 @@
|
||||
- CURRENT_SCHEMA=2，0.1.14+ 全部新字段靠 `normalizeGameState` 幂等兜底（worldSim/era/prosperity/stance/worldAnnals…）+ `loadState` 过 `migrateIfNeeded`（TOO_NEW 抛 MigrationError）。
|
||||
- **为什么**：v1→v2 后才真正需要"转换"的只有一次；其余靠兜底。升 v3 无真实转换内容（每轮审计结论一致：**不升**）。
|
||||
|
||||
### 7. 线程定论（0.1.21 实测）
|
||||
### 7. 世界种子与 MOD（0.1.24-0.1.26 新决策）
|
||||
- **worldgen 独立派生 rng**：世界布局与玩法随机序列彻底分离——同 seed 世界可重放、且玩法金钟罩不被生成器移动（0.1.24 架构地基）。
|
||||
- **MOD = 插件一等子类**：不发明第二套内容管线——模组 JSON→CotycPlugin→PluginManager（持久化/双闸/回滚捡现成）；规范（0.1.26）落为 MOD_GUIDE + schema 校验；**零脚本**（安全+指纹双保险）；**只影响新开档**（老档世界变形成档记录）。
|
||||
- **"落档则永稳"纪律**：凡世界实例内容（NPC defs/关系网/era/市场偏移/ MOD 集）全进 `state.worldGen`——读过即稳；两次踩坑（0.1.24 defs 不落档→读档软瘫；0.1.25 修复）教会我们：**确定性世界必须"记其所生"**。
|
||||
|
||||
### 8. 线程定论（0.1.21 实测）
|
||||
- 引擎 = renderer 主线程同步，`advanceMonth` 2160 月平均 **0.05ms/tick**；拖帧热点是 UI 全量渲染 + 存档 stringify（已修：精订阅/节流/截断）。
|
||||
- **为什么不做 Worker**：0.05ms 换线程是负收益工程；真问题（UI 渲染、OPFS 成本）已定位修复。
|
||||
|
||||
@@ -74,6 +84,8 @@
|
||||
4. **duplicate 时轮/双注册**（0.1.15）：restore 重建世界不重建内核 → 时钟注册 12→24 跑双倍。→ 教训：单例内核 + 回档测试。
|
||||
5. **事件闸竞态**（0.1.20）：单闸无条件 return → raid/军事线被日常事件饿死；被吞不写 CD 下月重试（白烧 rng 不落地）。→ 教训：**同 tick 多事件系统必须做优先级评测**。
|
||||
6. **每 tick 全量存档**（0.1.20）：autosaveEvery 死代码 + saveChronicle O(N) 逐条查询 → 2160 月档每 tick 数千 OPFS。→ 教训：**autosave 节流必须真实接线；冗余表用增量写**。
|
||||
6b. **确定性世界"记其所生"遗漏**（0.1.24→0.1.25）：worldGen 只存摘要不存 NPC defs → 读档后动态家族（n-g-*）npcById 全 miss，贸易/外交/战斗静默降级（软性瘫痪）。→ 教训：**凡"生成"的内容必落档**（worldGen.npcs + 幂等重注册）。
|
||||
6c. **聚合注册表默认值零漂**（0.1.26 验证）：灾因表/词库池改造为聚合时——默认表不动、指纹不漂（金钟罩不红的唯一路径）。→ 教训：**扩展点一律"默认优先、注册追加"**。
|
||||
7. **修改覆盖事故**（爸爸点名）：批量 python 替换命中旧文本 / `git checkout` 回滚误伤 / 链式 replace 重复属性。→ 教训：**修改纪律**（原子提交、替换三步断言、禁整文件 checkout、小步绿灯再前进）。
|
||||
8. **模块单例纪律**：MetonaSqlark 同库同 tab 一次连接（ARIA_LOCKED）→ 单例存取。
|
||||
|
||||
@@ -94,7 +106,13 @@
|
||||
5. NPC 四家是固定成分（无"覆灭/新贵补位"——0.1.19 留作 0.1.22+ 候选）；附庸/吞并仅 UI"衰"标记。
|
||||
6. `worldsim` 的能力卡开关无独立钩子（viaCap 恒真已注册，实际不可关）——如需可关需重构。
|
||||
|
||||
## 七、如何开始修改（给下一个智能体的路径）
|
||||
## 七、已知技术债补充（0.1.26）
|
||||
|
||||
7. MOD 目录形态仅支持单文件（目录/分包/依赖多个 .cotymod 自动解析留待）。
|
||||
8. CALAMITY 与 WORLDSTIM 数值表的大规模注入（多 MOD 叠加平衡）未做。
|
||||
9. NPC 四家之外的"中期势力轮替"曲线（newborn 频度/覆灭线）仍单参数，可寻参数化。
|
||||
|
||||
## 八、如何开始修改（给下一个智能体的路径）
|
||||
|
||||
```
|
||||
1. 读 AGENTS.md（红线）→ 2. 读本文件（意图）→ 3. 跑 npm test & typecheck 确认绿
|
||||
@@ -102,7 +120,7 @@
|
||||
改结构：注册进 clocks/plugins；世界循环参数唯一权威 = worldsim-data.ts
|
||||
→ 5. 改 UI：先改 store（revision）再改组件；纯逻辑放 game/engine 可测
|
||||
→ 6. 加测试：双金钟罩不动，新增用例挂 tests/xxx-0.1.x.test.ts（按主题命名）
|
||||
→ 7. 提交前：npm test + typecheck + （GUI 冒烟需 WSLg 在线）+ 更新三份文档
|
||||
→ 7. 提交前：npm test（47 套件 1047+）+ typecheck + （GUI 冒烟需 WSLg 在线）+ 更新三份文档 + MOD_GUIDE（触 MOD 时）
|
||||
```
|
||||
|
||||
**一句话原则**：先复现、再小改、后金钟罩。改坏确定性比改错玩法更危险；改数值去 worldsim-data，改流程去 clocks，改事件去 fire()。
|
||||
|
||||
Reference in New Issue
Block a user