ChronicleOfTheImmortalClan/docs/PROJECT_MEMORY.md

项目记忆 · 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
0.1.33	闭环·流光	物品生态闭环（符箓开战生效/僵尸物品归位/灾年入产——A1-A3 高危断链修复）；引擎止血 15 项（tribBoost 清零/assistAlly 先校验/回声空池守卫/版本透传/noAutoCreate 等）；UI 动效打磨（Modal 淡入/DriftLayer 节点清理/季节色对月/rAF 停帧节能）；测试 5009→5230

三、关键架构决策（及为什么）

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 消耗（自动消耗实现——金钟罩安全）；新增效果尽量走"已有结算点"（渡劫/战斗结束时挂钩）。

8c. 闭环与动效两纪律（0.1.33）

• 闭环纪律：物品/生产改动自检三问——①产出物有物品表定义吗？②消耗有真实入口吗？③数值真的被消费了吗？(A1 符箓不生效/A2 幽灵物品/A3 灾年算而未用=三问失败案例)
• 动效纪律：任何常驻动画/定时器必须考虑"空态即停、事件即醒"；季节/色温一律以游戏时为准（data-season 单源），严禁系统时钟入游戏表现(fx-canvas 教训)。
• 改测试先看断言源自哪层：as never强转绕过校验、require混 TS import、模板变量未转义——都是本迭代 2 次绕路的教训；新矩阵一律顶层 import + 模板注意转义。

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. 测试规模 5230（89 套件矩阵域），后续新增机制优先在对应矩阵域追加参（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（89 套件 5230+）+ typecheck + （GUI 冒烟需 WSLg 在线）+ 更新三份文档 + MOD_GUIDE（触 MOD 时）

一句话原则：先复现、再小改、后金钟罩。改坏确定性比改错玩法更危险；改数值去 worldsim-data，改流程去 clocks，改事件去 fire()。