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:
+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