thzxx
29eb25524b
README：测试数 86/5009 + 版本沿革补 0.1.31/0.1.32 + 矩阵域 29→40 MOD_GUIDE：§10 速查更新——资源/材料 id 十种 + 符箓/灵酿 id + 来源速记（与真实掉落/建筑对应） + 建筑 id 补灵果园/灵木坊 + 篇章尾注 0.1.32 生态观（六类循环/消耗类零 rng 纪律） PROJECT_MEMORY：时间线 0.1.31/0.1.32 + 新决策 8b「物品六类生态观」 （材料循环/入池则活/零 rng 消耗纪律）+ 技术债测试数同步
146 lines
16 KiB
Markdown
146 lines
16 KiB
Markdown
# 项目记忆 · Chronicle of the Immortal Clan
|
||
|
||
> 这份文档是**项目叙事记忆**：记录设计哲学、关键决策、踩过的坑、平衡教训。
|
||
> 面向"下一个将要改这份代码的智能体/开发者"——先读它再动手，能避开九成弯路。
|
||
> 与 AGENTS.md 分工：AGENTS 记**技术红线**（怎么改是安全的），本文记**为什么是现在这样**（设计意图）。
|
||
|
||
---
|
||
|
||
## 一、这是什么
|
||
|
||
一款**修仙家族传承模拟器**：玩家扮演"家族意志"，经营一族数代兴衰——修炼突破、经营产出、秘境探索、四邻外交、婚丧嫁娶、百年定鼎。
|
||
|
||
- **情感价值主张**：不是"养一个角色变强"，是"看一家子走完一程"——后人翻族谱/史书/碑录时的回望感。
|
||
- **玩法落点**，按重要性排序：
|
||
1. 世代血脉（婚育/继嗣/谱系）——传承是主叙事；
|
||
2. 修炼纵深（境界/功法/悟道/渡劫）——成长是爽点；
|
||
3. 经营与外交（建筑/贸易/联姻/劫掠）——决策供给；
|
||
4. 叙事编织（编年史/列传/百年报告/定鼎/天下史观）——情绪收束。
|
||
- **0.1.14+ 的独特命题**：世界不是背景板——市场有真库存（供需呼吸/NPC 上桌/玩家回写）、NPC 有战略姿态（守成/扩张/隐忍/结盟）与恩怨网（蝴蝶效应）、时代有大势弧（盛世/乱世/末法与景气双向闭环）。**天下兴衰与家族命运互为因果**，这是本作与"个人养成+结算"类游戏的本质区别。
|
||
|
||
## 二、版本时间线（每迭代的"为什么"）
|
||
|
||
| 版本 | 主题 | 当时为什么做 |
|
||
|---|---|---|
|
||
| 0.1.0-0.1.5 | 核心循环 → 养成闭环 → 审计 → 百年定局 → 人物志 | 立四系统、给成长闭环、上线前清毒、补"收束"、破成员同质化 |
|
||
| 0.1.6-0.1.8 | 时轮与造化 → 仙门之钥 → 万物皆是插件 | 时间/随机统一（架构地基）→ 门面/能力卡/数据包 → 全部系统插件化 |
|
||
| 0.1.9-0.1.11 | 百年报告/迁移 v2 → 长线决断 → 收官打磨 | 情感复盘 → 全灭崩溃数值重建 → 二次审计+UX 三件套 |
|
||
| 0.1.12 | 金碧山河 | 画面情绪价值：SVG 素材、动效系统、舞美 |
|
||
| 0.1.13 | 交付与回档 | 工艺修复 + 存储直连回档（玩家资产安全） |
|
||
| **0.1.14** | **大重构：GameEngine 门面 + WorldSim** | 引擎/UI 边界彻底划清：世界自进化（市场/NPC/快讯）作为独立 sim 层 |
|
||
| 0.1.15 | 深度审计 | 重构后必有一批缺陷；修 restore 双注册/引擎锁死等 7 P0 |
|
||
| 0.1.16 | 资源闭环 × 世情入味 | "灵石无压力、资源无出口"——修为经济化/炼丹概率化/铸器/灵脉收益 |
|
||
| 0.1.17 | 天下为市 | 市场从"幽灵振荡器"变"真库存"：玩家与 NPC 都能撼动行情——**世界对玩家单边透明死穴** |
|
||
| 0.1.18 | 时代绘卷 + 特效入引擎 | 世界缺大周期——世纪弧 era；特效从 UI 正则猜事件→引擎语义出口（onFx） |
|
||
| 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 对比度） |
|
||
| 0.1.27 | 活水长流 | **180 年模拟实测驱动**：生灭零触发/全图 900 打卡——门槛/era 调制/顶峰衰；修为↔市场回环；世鉴；测试规模 1054→**2000** |
|
||
| 0.1.28 | 稳石 | **第三轮全量审计**：词库池无回滚（重放漂移）/新贵不落档（读档僵尸）/校验死代码化/MOD 读档静默消失/快讯展示冻结/导出单行道——六项「书面承诺与实际不符」全歼 + 指纹补盲 |
|
||
| 0.1.29 | 续命 | **第四轮审计**（3seed×183 年实测）：170 年零出生活人老人院——续代四刀（生育窗/天年 200/族外婚注入/年胎 cap 稳态 25）；传薪 224 连发；敌强度 5000+ 碾压 |
|
||
| 0.1.30 | 兼济 | 人口-世界成本（人多粮少）/世界关注度（匹夫无罪）；MOD 生态成型（内置仓库/冲突矩阵/预览/API 清单）；**测试 2014→3006** |
|
||
| 0.1.31 | 万物皆可 MOD | 内容面总攻（物品/功法/建筑表达式 DSL/职事/志向/阵型/性格七口）+ MOD 类型（kind）+ 数值松弛（ERA_DURA/REGION_TIDE 聚合零漂）；测试 3006→4006 |
|
||
| 0.1.32 | 万宝琳琅 | 物品六类化（含符箓/灵酿新用途——武备消耗/回气）；新材料七种入世界循环（灵玉灵木兽皮灵果入池、新建筑灵果园灵木坊）；生产泛化（produceTable 全键）；**测试 4006→5009** |
|
||
|
||
## 三、关键架构决策（及为什么）
|
||
|
||
### 1. 纯 TS 引擎 + 确定性种子流
|
||
- `src/renderer/game/` 无 React/DOM import，vitest 直测；引擎域零 `Math.random`（真实存在 0 处，唯一播种走 `RngHub.rollSeed()`）。
|
||
- sfc32 随机种，同 seed 全程重放；**双金钟罩** = 3 seed × 3 档（47/100/180 年）× 两条长跑（冻结世界 + 自动 resolve 现实世界）= 18 指纹。
|
||
- **为什么**：平衡调参要"可复现"；且 0.1.20 审计发现"直调冻结世界"的指纹锁的是事件流静止的假样本——补第二条 resolved 长跑才算真正锁住"现实"。
|
||
|
||
### 2. GameClock 七相位 + clocks 注册表
|
||
- 月度 phase：production→aging→cultivation→missions→events→diplomacy→epilogue；**新系统 = 注册一行，禁手改 `advanceMonth`**。
|
||
- 为什么：0.1.6 前每个 tick 体内散着调用，加系统必乱序→破坏随机→金钟罩红。
|
||
|
||
### 3. 事件闸（0.1.20 定稿）
|
||
- `fire(w,id,priority)` 是 pending **唯一**写入入口；高优可顶替（被顶替者入 `eventQueue` 月月兑现）；普通被占放弃。
|
||
- **为什么**：0.1.20 审计实证——raid 名义 0.03/月、实际落地 18%（11 命中仅 2 落地），日常事件每月占闸 70~86%，军事线被打 1/5 折扣。且传薪曾同年重复 12 次、渡劫直写会覆盖既有 pending。事件闸语义必须文档化。
|
||
|
||
### 4. WorldSim 世界自演进（0.1.14+ 的 4 层递进）
|
||
- ① 市场实体化（真库存/供需/NPC/玩家回写）→ ② NPC 行为战略（姿态/景气/恩怨网/蝴蝶效应）→ ③ 世纪弧 era → ④ **era↔景气双向闭环**（世界温度反馈转移概率）。
|
||
- **为什么**：模拟器世界"只单方向驱动玩家"会像纸片；双向因果（玩家动作→市场→时代→NPC 行为→玩家的外交与局势）才是"自进化"的真义。`worldsim-data.ts` 是数值唯一权威（含 POOL_BASE/ERO_CONF/REGION_TIDE），调平衡改它不动流程。
|
||
|
||
### 5. 引擎-表现双通道
|
||
- 引擎语义事件经 `World.out`（WorldEventBus）：onLog/onChronicle/onBattle/pending/gameOver/yearPaper/**onFx**（0.1.18 语义特效）；UI `makeBus` 桥接（音效/日志/粒子）。特效发射零 rng（0.1.18 明训：**特效随机归渲染层，否则金钟罩崩**）。
|
||
|
||
### 6. 存档策略：normalize 即迁移
|
||
- CURRENT_SCHEMA=2，0.1.14+ 全部新字段靠 `normalizeGameState` 幂等兜底（worldSim/era/prosperity/stance/worldAnnals…）+ `loadState` 过 `migrateIfNeeded`（TOO_NEW 抛 MigrationError）。
|
||
- **为什么**：v1→v2 后才真正需要"转换"的只有一次；其余靠兜底。升 v3 无真实转换内容（每轮审计结论一致：**不升**）。
|
||
|
||
### 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.29-0.1.30 新平衡观）
|
||
- **续代是玩法命脉**：0.1.29 实测"170 年零出生"说明 0.1.1 以来内部通婚+固定生育窗是游戏最大暗伤——家族模拟器必须先"传得下去"再谈"传得好"。修复四刀（生育窗境界延长/天年 200/族外婚注入/年胎 cap）后人口稳态 ~25 成为设计常量。
|
||
- **规模即代价**：人口 >20 吃世界池（人多粮少）、战力超均值×2 举世瞩目（匹夫无罪）——"变大变强"天然有世界级反馈，防单边最优解。
|
||
|
||
### 8b. 物品六类生态观（0.1.32）
|
||
- **资源分层**（resource→material→成品）让"材料循环"成立：灵木→符纸→符箓（战斗消耗）、灵果→灵酿（回气）——每类物品都要有"入口（产/采/掉）→出口（用/卖/烧）"，防止库存死水（同 0.1.16 灵石出口教训）。
|
||
- **新物产入池即活**：仅定义物品不够——只有进了 POOL_BASE/MARKET_IDS 才参与世界呼吸/NPC 贸易/灾年超卖（0.1.32 四同步（四新增键入池）是关键，否则"只躺仓库"）。
|
||
- **消耗类物品的纪律**：符箓/灵酿效果必须**零 rng 消耗**（自动消耗实现——金钟罩安全）；新增效果尽量走"已有结算点"（渡劫/战斗结束时挂钩）。
|
||
|
||
### 9. 线程定论（0.1.21 实测）
|
||
- 引擎 = renderer 主线程同步，`advanceMonth` 2160 月平均 **0.05ms/tick**；拖帧热点是 UI 全量渲染 + 存档 stringify（已修：精订阅/节流/截断）。
|
||
- **为什么不做 Worker**：0.05ms 换线程是负收益工程；真问题（UI 渲染、OPFS 成本）已定位修复。
|
||
|
||
## 四、踩过的坑（高价值教训）
|
||
|
||
1. **金钟罩盲区**：560 月（47 年）听不见 180 年；且"直调冻结世界"指纹锁的是假样本（事件闸永驻、raid 永不落地）。→ 教训：**确定性验证要覆盖寿命尺度 + 现实长跑**（0.1.20 双基线）。
|
||
2. **era flow 权重和=1 → 无延续档**：`roll<acc` 恒真，第一年即转移，ERA_DURA 全死码——"看着合理其实错"。→ 教训：**概率转移表永远留"延续"权重**（和<1），测试断言 sum<1。
|
||
3. **潮汐供给符号反向**：`1-(tide-1)*k` 在潮高 1.35 时供给 ×0.895（注释承诺 ×1.3），末法反而供给过剩。→ 教训：**每个乘子写测试断言方向**（tide>1 必丰）。
|
||
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 验证）：灾因表/词库池改造为聚合时——默认表不动、指纹不漂（金钟罩不红的唯一路径）。→ 教训：**扩展点一律"默认优先、注册追加"**。
|
||
6d. **实测优先于直觉**（0.1.27）：180 年模拟推翻了"生灭千秋已实现"的直觉——零触发。→ 教训：**宣称完成的机制必须被长跑实测证伪一次**（同金钟罩盲区教训）。
|
||
6e. **承诺-实现间隙**（0.1.28）：预检"只活在测试里"、worldNum"文档有字段零调用"、bundle"导出自产不能自食"、MOD 读档"静默消失"——四个"写了但没接"。→ 教训：**文档宣称的能力必须有一条真实路径测试**（审计先查"声明 vs 调用"，比查"对不对"更易出真金）。
|
||
7. **修改覆盖事故**（爸爸点名）：批量 python 替换命中旧文本 / `git checkout` 回滚误伤 / 链式 replace 重复属性。→ 教训：**修改纪律**（原子提交、替换三步断言、禁整文件 checkout、小步绿灯再前进）。
|
||
8. **模块单例纪律**：MetonaSqlark 同库同 tab 一次连接（ARIA_LOCKED）→ 单例存取。
|
||
|
||
## 五、平衡哲学（玩起来正确的普适原则）
|
||
|
||
- **修炼快感 > 真实性**：30 岁炼气、50 岁筑基、百岁金丹，不按修真文教条拉长。
|
||
- **世代窗口**：每代 25-30 年，一回合 1 月，两百步见代际更替。
|
||
- **失败必须有出口**：渡劫失败跌伤为主（陨落限高阶）；事件悬置自动压制不锁死；断供拒单只到 0.35 且有世界供给回填（不造死局）。
|
||
- **资源漏斗有出口**：修为耗草（0.1.16）、兽核炼器、灵石养丹/调停/援兵——每个产出都有消耗侧；**市场超卖有反噬**（谷贱伤农）。
|
||
- **世界不是背景板**：玩家的交易/战争/结盟都会改变行情、NPC 势力与时代走向——决策有代价才有味道（0.1.17-0.1.21 一以贯之）。
|
||
|
||
## 六、已知技术债（诚实清单）
|
||
|
||
1. `realms.ts` 的 `expBase/expGrowth/maxRealmExp` 未参与计算（历史摆设，勿信勿用）。
|
||
2. GameFacade act 通道与面板直调并存（**仲裁结论**：直调是事实通道、act 为测试/自动化通道——actDirect 已补齐 24 项等价映射）。
|
||
3. `guide.ts`（引导任务）只做 UI 条，钩子目标点不完（"提示"非"强制"）。
|
||
4. `family.flag` 长线键已有 3 年剪枝、但 `state.missions/missionIds` 只增不减（未剪枝）。
|
||
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 频度/覆灭线）仍单参数，可寻参数化。
|
||
10. **测试规模 5009**（86 套件矩阵域），后续新增机制优先在对应矩阵域追加参（seed×组合），避免重开大文件。
|
||
11. **缓做项（0.1.28 审计定案）**：declineYears 盛世误触/闪烁——重平衡归 0.1.29 独立调参（避免二次基线漂移）；CALAMITY_FAMILY 独立口收益低（灾因口已覆盖）；ERA_DURA/REGION_TIDE 松弛版数值口 0.1.29+（必须走"默认优先+聚合"模式）。
|
||
|
||
## 八、如何开始修改（给下一个智能体的路径）
|
||
|
||
```
|
||
1. 读 AGENTS.md（红线）→ 2. 读本文件（意图）→ 3. 跑 npm test & typecheck 确认绿
|
||
→ 4. 改引擎：先改数据（data/ 或 sim/worldsim-data.ts）再改逻辑，小步跑金钟罩；
|
||
改结构：注册进 clocks/plugins；世界循环参数唯一权威 = worldsim-data.ts
|
||
→ 5. 改 UI：先改 store（revision）再改组件；纯逻辑放 game/engine 可测
|
||
→ 6. 加测试：双金钟罩不动，新增用例挂 tests/xxx-0.1.x.test.ts（按主题命名）
|
||
→ 7. 提交前：npm test（86 套件 5009+）+ typecheck + （GUI 冒烟需 WSLg 在线）+ 更新三份文档 + MOD_GUIDE（触 MOD 时）
|
||
```
|
||
|
||
**一句话原则**：先复现、再小改、后金钟罩。改坏确定性比改错玩法更危险；改数值去 worldsim-data，改流程去 clocks，改事件去 fire()。
|