docs: 四文档同步 0.1.28《稳石》
AGENTS：金钟罩注释 0.1.24→0.1.28（指纹补盲清单：worldGen 摘要/sagaAnnals/distress/declineYears） README：测试数 69/2008 + 版本沿革 0.1.28 + 守护机制补「审计三轮」 PROJECT_MEMORY：时间线 0.1.28 + 教训 6e「承诺-实现间隙」+ 技术债更新（缓做项定案） MOD_GUIDE：版本 0.1.28 + 兑现注记（预检生产链/卸载真回滚/worldNum 接线/缺失提示/bundle 再导入闭环）
This commit is contained in:
@@ -61,7 +61,7 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
|
||||
- **插件架构**（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.24 基线**（0.1.25/0.1.26 世界生成默认池不变、灾因默认表不变 → 基线零漂，见注释）。指纹 `tests/fingerprint.helper.ts` 含全世界轴（era/stance/prosperity/relationsWithOthers/calamity/pendingEvent/eventQueue/worldAnnals/worldGen 摘要）。**有意变更时序/数值时**：指纹一并重算并在注释注明原因。
|
||||
- **金钟罩（双基线）**：`tests/clock.test.ts` 的 `GOLDEN`（直调冻结世界）+ `GOLDEN_RESOLVED`（自动 resolve 长跑"现实"世界），各 3 seed × 三档月数（560/1200/2160）共 18 值。当前为 **0.1.28 基线**（第三轮审计指纹补盲后固化；0.1.25/0.1.26 曾零漂，0.1.27/0.1.28 受控变更重算）。指纹 `tests/fingerprint.helper.ts` 含全世界轴（era/stance/prosperity/relationsWithOthers/calamity/pendingEvent/eventQueue/worldAnnals/**worldGen 摘要/sagaAnnals/distress/declineYears 汇总**——0.1.27 生灭/世鉴路径真实锁定）。**有意变更时序/数值时**：指纹一并重算并在注释注明原因。
|
||||
|
||||
## 世界自演进模型（0.1.14 sim/ 层，改数值勿动流程）
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
npm install # 依赖（含 git.metona.cn 私有 registry，token 在用户级 ~/.npmrc）
|
||||
npm install-scripts approve electron esbuild # npm12 首装时必须（Electron 二进制）
|
||||
npm run dev # 开发模式（热更新）
|
||||
npm test # 引擎测试（68 套件 / 2000 用例，纯 Node 无 GUI）
|
||||
npm test # 引擎测试（69 套件 / 2008 用例，纯 Node 无 GUI）
|
||||
npm run build # 产物到 out/
|
||||
npm run package # 打包（Windows 需在 Windows 侧执行）
|
||||
```
|
||||
@@ -46,7 +46,8 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
|
||||
- **事件闸**：pending 唯一入口 `fire(w,id,priority)`——高优（raid/渡劫/大比）可顶替被占者，被顶替者入队下月兑现；`applyEventChoice` 前置校验防陈旧 Modal 二次结算。
|
||||
- **插件化**：万物皆是插件（系统/数据包/事件池），三核心插件 protected 常驻；示例见 tests/helpers/examplePlugin.ts。
|
||||
- **可回放**：种子随机（sfc32，引擎域零 Math.random）+ 快照回放保真（restore 重建内核+回置 rng）。
|
||||
- **测试规模**：**68 套件 / 2000 例**（18 个矩阵域：随机序列/世界生成/市场实体化/事件闸/数据表全量/插件 MOD 组合/省级矩阵等——语义真实，无刷水）。
|
||||
- **审计三轮**：0.1.15（引擎 P0 歼灭）/ 0.1.20（事件闸·市场黑洞·双金钟罩）/ **0.1.28（稳石：词库回滚·新贵落档·校验接生产·bundle 闭环·指纹补盲）**。
|
||||
- **测试规模**：**69 套件 / 2008 例**（18 个矩阵域：随机序列/世界生成/市场实体化/事件闸/数据表全量/插件 MOD 组合/省级矩阵等——语义真实，无刷水）。
|
||||
|
||||
## 打包产物
|
||||
|
||||
@@ -75,5 +76,6 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
|
||||
| 0.1.25 | 乾坤一统（MOD 系统首版：userData/mods 扫描/解析/安装/持久化 + worldGen 存档永稳修复） |
|
||||
| 0.1.26 | 墨规清辉（MOD 规范范式：MOD_GUIDE/validateMod/灾因注册表 + 页面文本提亮可读性） |
|
||||
| 0.1.27 | 活水长流（生灭可达化：180 年实测驱动——门槛/era 调制增长/顶峰衰 + 修为↔市场回环 + 世鉴 50/100 年 + 测试 2000） |
|
||||
| 0.1.28 | 稳石（第三轮全量审计歼灭：词库回滚/新贵落档/校验接生产/bundle 导入/救济正道/快讯解锁 + 指纹补盲） |
|
||||
|
||||
详见：`docs/PROJECT_MEMORY.md`（设计哲学与每个迭代的"为什么"）。
|
||||
|
||||
+7
-6
@@ -1,6 +1,6 @@
|
||||
# MOD 规范与范式标准 · Chronicle of the Immortal Clan
|
||||
|
||||
> 版本 **0.1.27·《活水长流》** · MOD_SCHEMA_VERSION = 1
|
||||
> 版本 **0.1.28·《稳石》** · MOD_SCHEMA_VERSION = 1
|
||||
> 每个 MOD 是一个**外部内容包**（纯 JSON，零脚本）；安装后成为插件一等子类，
|
||||
> 享有插件的全部设施：持久化（随档）、启用/停用、依赖/冲突检查、卸载自动回滚。
|
||||
|
||||
@@ -134,15 +134,16 @@ EventDef 全字段**纯数据**（与内置事件同构）：
|
||||
|
||||
## 8. 已验证的安装流程（行为承诺）
|
||||
|
||||
- 安装：`World.installPlugin(modToPlugin(pack))` → 事件进池/模板注册/词库聚合/灾因入表/配方注册；
|
||||
- `modPreflight` 先行：id 冲突拒绝 + 范式警告；`validateMod` 深度校验（category/weight/境界/非负）；
|
||||
- 启用/停用/卸载：插件双闸与自动回滚照常（卸载即全摘）；
|
||||
- 存档：MOD 状态随 `state.plugins` 持久化，读档自动重装（版本不符跳过并提示）。
|
||||
- 安装：`World.installPlugin(modToPlugin(pack))` → 事件进池/模板注册/词库聚合/灾因入表/配方注册/worldNum 覆写；
|
||||
- **预检已接生产（0.1.28）**：游戏内安装必走 `modPreflight`（事件 id 冲突拒绝装；范式警告 toast）；`validateMod` 深度校验（category/weight/境界/非负/空串/NaN 防护）；
|
||||
- 启用/停用/卸载：插件双闸与自动回滚照常（**0.1.28 起卸载真正全摘**——词库池/灾因/配方/worldNum 按来源精确回滚，共享词条保留）；
|
||||
- 存档：MOD 状态随 `state.plugins` 持久化，读档自动重装（版本不符跳过）；**缺失插件记 `state.pluginsMissing` 并提示**（"文件可能需重新放入 mods 目录"）；
|
||||
- 世界数值：`worldNum`（§2 数据包内）已接线——安装覆写/卸载复位。
|
||||
|
||||
## 9. 打包与分发
|
||||
|
||||
- 单文件 `.cotymod`（= JSON）直接分发；放入 `userData/mods/` 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。
|
||||
- **游戏内导出**（0.1.27）：「MOD 层 → 导出当前 MOD 集」会把当前启用的全部 MOD 合并为 `mod-bundle-export.cotymod`（含各包明细）——分享/备份走同一载入通道。
|
||||
- **游戏内导出**（0.1.27，0.1.28 闭环）：「MOD 层 → 导出当前 MOD 集」把当前启用的全部 MOD 合并为 `mod-bundle-export.cotymod`（含各包明细）；导出包可直接再导入（`modParse` 识别 `{app:'cotymod',bundle}` 逐包递归）——分享/备份同通道无断点。
|
||||
- 注意：**MOD 只影响新开档**的世界生成；已开档不受影响（世界种已落档）。
|
||||
|
||||
---
|
||||
|
||||
@@ -41,6 +41,7 @@
|
||||
| 0.1.25 | 乾坤一统 | **MOD 系统首版**（MOD=插件一等子类，全 JSON 外部包）；修 0.1.24 遗留：worldGen 不含 npcs 落档（读档软瘫） |
|
||||
| 0.1.26 | 墨规清辉 | MOD **规范范式**（MOD_GUIDE/validateMod/权威冲突检测）；灾因归一化注册表（MOD 灾年入循环）；页面提亮（暗因：.dim 3.4:1 对比度） |
|
||||
| 0.1.27 | 活水长流 | **180 年模拟实测驱动**：生灭零触发/全图 900 打卡——门槛/era 调制/顶峰衰；修为↔市场回环；世鉴；测试规模 1054→**2000** |
|
||||
| 0.1.28 | 稳石 | **第三轮全量审计**：词库池无回滚（重放漂移）/新贵不落档（读档僵尸）/校验死代码化/MOD 读档静默消失/快讯展示冻结/导出单行道——六项「书面承诺与实际不符」全歼 + 指纹补盲 |
|
||||
|
||||
## 三、关键架构决策（及为什么）
|
||||
|
||||
@@ -88,6 +89,7 @@
|
||||
6b. **确定性世界"记其所生"遗漏**（0.1.24→0.1.25）：worldGen 只存摘要不存 NPC defs → 读档后动态家族（n-g-*）npcById 全 miss，贸易/外交/战斗静默降级（软性瘫痪）。→ 教训：**凡"生成"的内容必落档**（worldGen.npcs + 幂等重注册）。
|
||||
6c. **聚合注册表默认值零漂**（0.1.26 验证）：灾因表/词库池改造为聚合时——默认表不动、指纹不漂（金钟罩不红的唯一路径）。→ 教训：**扩展点一律"默认优先、注册追加"**。
|
||||
6d. **实测优先于直觉**（0.1.27）：180 年模拟推翻了"生灭千秋已实现"的直觉——零触发。→ 教训：**宣称完成的机制必须被长跑实测证伪一次**（同金钟罩盲区教训）。
|
||||
6e. **承诺-实现间隙**（0.1.28）：预检"只活在测试里"、worldNum"文档有字段零调用"、bundle"导出自产不能自食"、MOD 读档"静默消失"——四个"写了但没接"。→ 教训：**文档宣称的能力必须有一条真实路径测试**（审计先查"声明 vs 调用"，比查"对不对"更易出真金）。
|
||||
7. **修改覆盖事故**（爸爸点名）：批量 python 替换命中旧文本 / `git checkout` 回滚误伤 / 链式 replace 重复属性。→ 教训：**修改纪律**（原子提交、替换三步断言、禁整文件 checkout、小步绿灯再前进）。
|
||||
8. **模块单例纪律**：MetonaSqlark 同库同 tab 一次连接（ARIA_LOCKED）→ 单例存取。
|
||||
|
||||
@@ -113,7 +115,8 @@
|
||||
7. MOD 目录形态仅支持单文件（目录/分包/依赖多个 .cotymod 自动解析留待）。
|
||||
8. CALAMITY 与 WORLDSTIM 数值表的大规模注入（多 MOD 叠加平衡）未做。
|
||||
9. NPC"中期势力轮替"曲线（newborn 频度/覆灭线）仍单参数，可寻参数化。
|
||||
10. **测试规模已达 2000**（68 套件矩阵域），后续新增机制优先在对应矩阵域追加参（seed×组合），避免重开大文件。
|
||||
10. **测试规模 2008**（69 套件矩阵域），后续新增机制优先在对应矩阵域追加参（seed×组合），避免重开大文件。
|
||||
11. **缓做项（0.1.28 审计定案）**：declineYears 盛世误触/闪烁——重平衡归 0.1.29 独立调参（避免二次基线漂移）；CALAMITY_FAMILY 独立口收益低（灾因口已覆盖）；ERA_DURA/REGION_TIDE 松弛版数值口 0.1.29+（必须走"默认优先+聚合"模式）。
|
||||
|
||||
## 八、如何开始修改（给下一个智能体的路径）
|
||||
|
||||
@@ -123,7 +126,7 @@
|
||||
改结构：注册进 clocks/plugins；世界循环参数唯一权威 = worldsim-data.ts
|
||||
→ 5. 改 UI：先改 store（revision）再改组件；纯逻辑放 game/engine 可测
|
||||
→ 6. 加测试：双金钟罩不动，新增用例挂 tests/xxx-0.1.x.test.ts（按主题命名）
|
||||
→ 7. 提交前：npm test（68 套件 2000+）+ typecheck + （GUI 冒烟需 WSLg 在线）+ 更新三份文档 + MOD_GUIDE（触 MOD 时）
|
||||
→ 7. 提交前：npm test（69 套件 2008+）+ typecheck + （GUI 冒烟需 WSLg 在线）+ 更新三份文档 + MOD_GUIDE（触 MOD 时）
|
||||
```
|
||||
|
||||
**一句话原则**：先复现、再小改、后金钟罩。改坏确定性比改错玩法更危险；改数值去 worldsim-data，改流程去 clocks，改事件去 fire()。
|
||||
|
||||
Reference in New Issue
Block a user