MetonaTeam/ChronicleOfTheImmortalClan
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 四文档同步 0.1.30《兼济》

Browse Source 
README：测试数 81/3006 + 版本沿革补 0.1.29/0.1.30 + 审计轮次改「四轮」
PROJECT_MEMORY：时间线 0.1.29/0.1.30 + 新平衡观决策第 8 条（续代是玩法命脉/规模即代价）
MOD_GUIDE：版本 0.1.30 + §8.5 官方范例（风物集/战备解军观摩指南）+ 预览影响标注
AGENTS：0.1.30 小节与测试 3006（上轮已写，核对无漂）
This commit is contained in:
thzxx
2026-08-23 20:29:06 +08:00
parent 8a81022862
commit 716a91bd96
3 changed files with 24 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+5 -3
View File
@@ -12,7 +12,7 @@
npm install # 依赖（含 git.metona.cn 私有 registry，token 在用户级 ~/.npmrc） npm install # 依赖（含 git.metona.cn 私有 registry，token 在用户级 ~/.npmrc）
npm install-scripts approve electron esbuild # npm12 首装时必须（Electron 二进制） npm install-scripts approve electron esbuild # npm12 首装时必须（Electron 二进制）
npm run dev # 开发模式（热更新） npm run dev # 开发模式（热更新）
npm test # 引擎测试（69 套件 / 2008 用例，纯 Node 无 GUI） npm test # 引擎测试（81 套件 / 3006 用例，纯 Node 无 GUI）
npm run build # 产物到 out/ npm run build # 产物到 out/
npm run package # 打包（Windows 需在 Windows 侧执行） npm run package # 打包（Windows 需在 Windows 侧执行）
``` ```
@@ -46,8 +46,8 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
- **事件闸**：pending 唯一入口 `fire(w,id,priority)`——高优（raid/渡劫/大比）可顶替被占者，被顶替者入队下月兑现；`applyEventChoice` 前置校验防陈旧 Modal 二次结算。 - **事件闸**：pending 唯一入口 `fire(w,id,priority)`——高优（raid/渡劫/大比）可顶替被占者，被顶替者入队下月兑现；`applyEventChoice` 前置校验防陈旧 Modal 二次结算。
- **插件化**：万物皆是插件（系统/数据包/事件池），三核心插件 protected 常驻；示例见 tests/helpers/examplePlugin.ts。 - **插件化**：万物皆是插件（系统/数据包/事件池），三核心插件 protected 常驻；示例见 tests/helpers/examplePlugin.ts。
- **可回放**：种子随机（sfc32，引擎域零 Math.random）+ 快照回放保真（restore 重建内核+回置 rng）。 - **可回放**：种子随机（sfc32，引擎域零 Math.random）+ 快照回放保真（restore 重建内核+回置 rng）。
- **审计三轮**：0.1.15（引擎 P0 歼灭）/ 0.1.20（事件闸·市场黑洞·双金钟罩）/ **0.1.28（稳石：词库回滚·新贵落档·校验接生产·bundle 闭环·指纹补盲）**。 - **审计四轮**：0.1.15（引擎 P0 歼灭）/ 0.1.20（事件闸·市场黑洞·双金钟罩）/ 0.1.28（稳石：词库回滚·新贵落档·校验接生产·bundle 闭环·指纹补盲）/ **0.1.29（续命：续代断链·敌强度相对化·权重防洪）**。
- **测试规模**：**69 套件 / 2008 例**（18 个矩阵域：随机序列/世界生成/市场实体化/事件闸/数据表全量/插件 MOD 组合/省级矩阵等——语义真实，无刷水）。 - **测试规模**：**81 套件 / 3006 例**（29 个矩阵域：随机序列/世界生成/市场实体化/事件闸/数据表全量/插件 MOD 组合/省级矩阵等——语义真实，无刷水）。
## 打包产物 ## 打包产物
@@ -77,5 +77,7 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
| 0.1.26 | 墨规清辉（MOD 规范范式：MOD_GUIDE/validateMod/灾因注册表 + 页面文本提亮可读性） | | 0.1.26 | 墨规清辉（MOD 规范范式：MOD_GUIDE/validateMod/灾因注册表 + 页面文本提亮可读性） |
| 0.1.27 | 活水长流（生灭可达化：180 年实测驱动——门槛/era 调制增长/顶峰衰 + 修为↔市场回环 + 世鉴 50/100 年 + 测试 2000） | | 0.1.27 | 活水长流（生灭可达化：180 年实测驱动——门槛/era 调制增长/顶峰衰 + 修为↔市场回环 + 世鉴 50/100 年 + 测试 2000） |
| 0.1.28 | 稳石（第三轮全量审计歼灭：词库回滚/新贵落档/校验接生产/bundle 导入/救济正道/快讯解锁 + 指纹补盲） | | 0.1.28 | 稳石（第三轮全量审计歼灭：词库回滚/新贵落档/校验接生产/bundle 导入/救济正道/快讯解锁 + 指纹补盲） |
| 0.1.29 | 续命（第四轮全量审计歼灭：续代断链修复/敌强度相对化/权重防垄断/启用过滤/并发存档修复） |
| 0.1.30 | 兼济（人口-世界成本闭环 + 世界关注度（匹夫无罪）+ 内置 MOD 仓库/冲突矩阵/预览 + 测试 3006） |
详见：`docs/PROJECT_MEMORY.md`（设计哲学与每个迭代的"为什么"）。 详见：`docs/PROJECT_MEMORY.md`（设计哲学与每个迭代的"为什么"）。
docs/MOD_GUIDE.md
+10 -1
View File
@@ -1,6 +1,6 @@
# MOD 规范与范式标准 · Chronicle of the Immortal Clan # MOD 规范与范式标准 · Chronicle of the Immortal Clan
> 版本 **0.1.28·《稳石》** · MOD_SCHEMA_VERSION = 1 > 版本 **0.1.30·《兼济》** · MOD_SCHEMA_VERSION = 1
> 每个 MOD 是一个**外部内容包**（纯 JSON，零脚本）；安装后成为插件一等子类， > 每个 MOD 是一个**外部内容包**（纯 JSON，零脚本）；安装后成为插件一等子类，
> 享有插件的全部设施：持久化（随档）、启用/停用、依赖/冲突检查、卸载自动回滚。 > 享有插件的全部设施：持久化（随档）、启用/停用、依赖/冲突检查、卸载自动回滚。
@@ -140,6 +140,15 @@ EventDef 全字段**纯数据**（与内置事件同构）：
- 存档：MOD 状态随 `state.plugins` 持久化，读档自动重装（版本不符跳过）；**缺失插件记 `state.pluginsMissing` 并提示**（"文件可能需重新放入 mods 目录"）； - 存档：MOD 状态随 `state.plugins` 持久化，读档自动重装（版本不符跳过）；**缺失插件记 `state.pluginsMissing` 并提示**（"文件可能需重新放入 mods 目录"）；
- 世界数值：`worldNum`（§2 数据包内）已接线——安装覆写/卸载复位。 - 世界数值：`worldNum`（§2 数据包内）已接线——安装覆写/卸载复位。
## 8.5 官方范例（0.1.30）
游戏内置两枚示范包（设置 → MOD 层 → 内置仓库）可一键安装观摩：
- **风物集**（`fenwu-ji`）：词库注入（吴/江/雨 + 江南烟雨畔）+ 灾因「瘴雨」（brief 文案示范）——看怎么做"地域风物包"。
- **战备解军**（`zhanbei-xv`）：配方注入（灵纹刃）+ worldNum 覆写（供需微调）——看怎么做"数值平衡包"。
NewGame 开局预览会标注当前已装 MOD 集——**新档世界由 seed+MOD 集共同塑造**（老档不变形）。
## 9. 打包与分发 ## 9. 打包与分发
- 单文件 `.cotymod`（= JSON）直接分发；放入 `userData/mods/` 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。 - 单文件 `.cotymod`（= JSON）直接分发；放入 `userData/mods/` 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。
docs/PROJECT_MEMORY.md
+9 -3
View File
@@ -42,6 +42,8 @@
| 0.1.26 | 墨规清辉 | MOD **规范范式**（MOD_GUIDE/validateMod/权威冲突检测）；灾因归一化注册表（MOD 灾年入循环）；页面提亮（暗因：.dim 3.4:1 对比度） | | 0.1.26 | 墨规清辉 | MOD **规范范式**（MOD_GUIDE/validateMod/权威冲突检测）；灾因归一化注册表（MOD 灾年入循环）；页面提亮（暗因：.dim 3.4:1 对比度） |
| 0.1.27 | 活水长流 | **180 年模拟实测驱动**：生灭零触发/全图 900 打卡——门槛/era 调制/顶峰衰；修为↔市场回环；世鉴；测试规模 1054→**2000** | | 0.1.27 | 活水长流 | **180 年模拟实测驱动**：生灭零触发/全图 900 打卡——门槛/era 调制/顶峰衰；修为↔市场回环；世鉴；测试规模 1054→**2000** |
| 0.1.28 | 稳石 | **第三轮全量审计**：词库池无回滚（重放漂移）/新贵不落档（读档僵尸）/校验死代码化/MOD 读档静默消失/快讯展示冻结/导出单行道——六项「书面承诺与实际不符」全歼 + 指纹补盲 | | 0.1.28 | 稳石 | **第三轮全量审计**：词库池无回滚（重放漂移）/新贵不落档（读档僵尸）/校验死代码化/MOD 读档静默消失/快讯展示冻结/导出单行道——六项「书面承诺与实际不符」全歼 + 指纹补盲 |
| 0.1.29 | 续命 | **第四轮审计**（3seed×183 年实测）：170 年零出生活人老人院——续代四刀（生育窗/天年 200/族外婚注入/年胎 cap 稳态 25）；传薪 224 连发；敌强度 5000+ 碾压 |
| 0.1.30 | 兼济 | 人口-世界成本（人多粮少）/世界关注度（匹夫无罪）；MOD 生态成型（内置仓库/冲突矩阵/预览/API 清单）；**测试 2014→3006** |
## 三、关键架构决策（及为什么） ## 三、关键架构决策（及为什么）
@@ -74,7 +76,11 @@
- **MOD = 插件一等子类**：不发明第二套内容管线——模组 JSON→CotycPlugin→PluginManager（持久化/双闸/回滚捡现成）；规范（0.1.26）落为 MOD_GUIDE + schema 校验；**零脚本**（安全+指纹双保险）；**只影响新开档**（老档世界变形成档记录）。 - **MOD = 插件一等子类**：不发明第二套内容管线——模组 JSON→CotycPlugin→PluginManager（持久化/双闸/回滚捡现成）；规范（0.1.26）落为 MOD_GUIDE + schema 校验；**零脚本**（安全+指纹双保险）；**只影响新开档**（老档世界变形成档记录）。
- **"落档则永稳"纪律**：凡世界实例内容（NPC defs/关系网/era/市场偏移/ MOD 集）全进 `state.worldGen`——读过即稳；两次踩坑（0.1.24 defs 不落档→读档软瘫；0.1.25 修复）教会我们：**确定性世界必须"记其所生"**。 - **"落档则永稳"纪律**：凡世界实例内容（NPC defs/关系网/era/市场偏移/ MOD 集）全进 `state.worldGen`——读过即稳；两次踩坑（0.1.24 defs 不落档→读档软瘫；0.1.25 修复）教会我们：**确定性世界必须"记其所生"**。
### 8. 线程定论（0.1.21 实测） ### 8. 人口与关注度（0.1.29-0.1.30 新平衡观）
- **续代是玩法命脉**：0.1.29 实测"170 年零出生"说明 0.1.1 以来内部通婚+固定生育窗是游戏最大暗伤——家族模拟器必须先"传得下去"再谈"传得好"。修复四刀（生育窗境界延长/天年 200/族外婚注入/年胎 cap）后人口稳态 ~25 成为设计常量。
- **规模即代价**：人口 >20 吃世界池（人多粮少）、战力超均值×2 举世瞩目（匹夫无罪）——"变大变强"天然有世界级反馈，防单边最优解。
### 9. 线程定论（0.1.21 实测）
- 引擎 = renderer 主线程同步，`advanceMonth` 2160 月平均 **0.05ms/tick**；拖帧热点是 UI 全量渲染 + 存档 stringify（已修：精订阅/节流/截断）。 - 引擎 = renderer 主线程同步，`advanceMonth` 2160 月平均 **0.05ms/tick**；拖帧热点是 UI 全量渲染 + 存档 stringify（已修：精订阅/节流/截断）。
- **为什么不做 Worker**：0.05ms 换线程是负收益工程；真问题（UI 渲染、OPFS 成本）已定位修复。 - **为什么不做 Worker**：0.05ms 换线程是负收益工程；真问题（UI 渲染、OPFS 成本）已定位修复。
@@ -115,7 +121,7 @@
7. MOD 目录形态仅支持单文件（目录/分包/依赖多个 .cotymod 自动解析留待）。 7. MOD 目录形态仅支持单文件（目录/分包/依赖多个 .cotymod 自动解析留待）。
8. CALAMITY 与 WORLDSTIM 数值表的大规模注入（多 MOD 叠加平衡）未做。 8. CALAMITY 与 WORLDSTIM 数值表的大规模注入（多 MOD 叠加平衡）未做。
9. NPC"中期势力轮替"曲线（newborn 频度/覆灭线）仍单参数，可寻参数化。 9. NPC"中期势力轮替"曲线（newborn 频度/覆灭线）仍单参数，可寻参数化。
10. **测试规模 2008**（69 套件矩阵域），后续新增机制优先在对应矩阵域追加参（seed×组合），避免重开大文件。 10. **测试规模 3006**（81 套件矩阵域），后续新增机制优先在对应矩阵域追加参（seed×组合），避免重开大文件。
11. **缓做项（0.1.28 审计定案）**：declineYears 盛世误触/闪烁——重平衡归 0.1.29 独立调参（避免二次基线漂移）；CALAMITY_FAMILY 独立口收益低（灾因口已覆盖）；ERA_DURA/REGION_TIDE 松弛版数值口 0.1.29+（必须走"默认优先+聚合"模式）。 11. **缓做项（0.1.28 审计定案）**：declineYears 盛世误触/闪烁——重平衡归 0.1.29 独立调参（避免二次基线漂移）；CALAMITY_FAMILY 独立口收益低（灾因口已覆盖）；ERA_DURA/REGION_TIDE 松弛版数值口 0.1.29+（必须走"默认优先+聚合"模式）。
## 八、如何开始修改（给下一个智能体的路径） ## 八、如何开始修改（给下一个智能体的路径）
@@ -126,7 +132,7 @@
改结构：注册进 clocks/plugins；世界循环参数唯一权威 = worldsim-data.ts 改结构：注册进 clocks/plugins；世界循环参数唯一权威 = worldsim-data.ts
→ 5. 改 UI：先改 store（revision）再改组件；纯逻辑放 game/engine 可测 → 5. 改 UI：先改 store（revision）再改组件；纯逻辑放 game/engine 可测
→ 6. 加测试：双金钟罩不动，新增用例挂 tests/xxx-0.1.x.test.ts（按主题命名） → 6. 加测试：双金钟罩不动，新增用例挂 tests/xxx-0.1.x.test.ts（按主题命名）
→ 7. 提交前：npm test（69 套件 2008+）+ typecheck + （GUI 冒烟需 WSLg 在线）+ 更新三份文档 + MOD_GUIDE（触 MOD 时） → 7. 提交前：npm test（81 套件 3006+）+ typecheck + （GUI 冒烟需 WSLg 在线）+ 更新三份文档 + MOD_GUIDE（触 MOD 时）
``` ```
**一句话原则**：先复现、再小改、后金钟罩。改坏确定性比改错玩法更危险；改数值去 worldsim-data，改流程去 clocks，改事件去 fire()。 **一句话原则**：先复现、再小改、后金钟罩。改坏确定性比改错玩法更危险；改数值去 worldsim-data，改流程去 clocks，改事件去 fire()。