ChronicleOfTheImmortalClan/docs/PROJECT_MEMORY.md

项目记忆 · Chronicle of the Immortal Clan

这份文档是项目叙事记忆：记录设计哲学、关键决策、踩过的坑、平衡教训。 面向"下一个将要改这份代码的智能体/开发者"——先读它再动手，能避开九成弯路。 与 AGENTS.md 分工：AGENTS 记技术红线（怎么改是安全的），本文记为什么是现在这样（设计意图）。

---

一、这是什么

一款修仙家族传承模拟器：玩家扮演"家族意志"，经营一族数代兴衰——修炼突破、经营产出、秘境探索、四邻外交、婚丧嫁娶、百年定鼎。

• 情感价值主张：不是"养一个角色变强"，是"看一家子走完一程"——后人翻族谱/史书/碑录时的回望感。
• 玩法落点，按重要性排序：
  1. 世代血脉（婚育/继嗣/谱系）——传承是主叙事；
  2. 修炼纵深（境界/功法/悟道/渡劫）——成长是爽点；
  3. 经营与外交（建筑/贸易/联姻/劫掠）——决策供给；
  4. 叙事编织（编年史/列传/百年报告/定鼎）——情绪收束。

二、版本时间线（每迭代的"为什么"）

版本	主题	当时为什么做
0.1.0	核心循环	把"修仙+家族+经营+战斗"四系统全部立起来，形成可玩闭环
0.1.1	养成闭环+存档安全	指婚/装备/祭祖/回档：管理自主度决定模拟器粘性
0.1.2	宗族气韵	职事/悟道/谱系/碑录：让"传承"有可视载体
0.1.3	深度审计	刚做完新系统必有一批缺陷，上线前清毒
0.1.4	百年定局	模拟器缺"收束"：四维评分+十二称号+春秋原
0.1.5	人物志	成员同质化：志向/渡劫/列传/契合让"人"有戏
0.1.6	时轮与造化	时间与随机从"散装"走向"统一"（GameClock/RngHub）——架构地基
0.1.7	仙门之钥	门面/能力注册表/数据包：对外暴露与可拔插
0.1.8	万物皆是插件	把全部系统统一进插件协议（Manifest/依赖/卸载/追踪型钩子）
0.1.9	百年报告与发布	情感复盘（报告）＋工程收口（迁移管线/发布哨兵）
0.1.10	长线决断	审计发现全灭崩溃：修炼太慢+寿元短+渡劫误压——数值重建
0.1.11	收官打磨	二次审计（引擎8+UI11缺陷歼灭）+ UX 三件套（警讯/引导/格式化）

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

1. 纯 TS 引擎 + 确定性种子流

• src/renderer/game/ 无 React/DOM import，vitest 直测。
• sfc32 随机种，同 seed 全程重放；金钟罩=3 seed×3 档时长（47/100/180年）指纹固化。
• 为什么：模拟器平衡调参需要"可复现"；金钟罩把"改坏了确定性"变成"一秒red"。

2. GameClock 七相位

• 月度 phase：production→aging→cultivation→missions→events→diplomacy→epilogue；
• 年首三钩子：婚配→岁贡→族簿。新系统=注册一行，禁手改 advanceMonth。
• 为什么：0.1.6 前每个 tick 体内散着调用，加系统必乱序→破坏随机→金钟罩红。

3. 插件协议（0.1.8）

• 万物皆是插件：系统/数据包/事件池统一 Manifest；engine/pluginManager.ts 安装管线（依赖校验/异常回滚/追踪型上下文）。
• 三核心插件（Systems/Data/Events）protected 常驻。
• 为什么：玩法内容增量的"可插拔出口"；事件多池让第三方能注入事件。

4. 存档分层

• metona-sqlark 在 renderer（OPFS）+ {Slots} {迁移链}；v1→v2 迁移管线（0.1.9）。
• 为什么：浏览器持久化天生平台限制；预置迁移链防未来表变炸档。

5. UI 惯例

• zustand revision++ 是刷新惯例；facade 必须 openState/startNewGame 赋值；
• 警讯徽章（urgency）与引导任务（guide）做成 engine 侧纯函数，UI 只渲染。

四、踩过的坑（高价值教训）

1. 金钟罩盲区：560 月（47 年）只能听见"中期"，看不见"晚期"——0.1.10 之前全灭崩溃藏在这里。→ 教训：确定性验证要覆盖寿命尺度（现在三档到 180 年）。
2. 渡劫误压制：eventRoll 一处"自动压制"让 qi8→筑基永不可达（境界峰恒炼气）。→ 教训：自动回退/悬空逻辑必须单测"有人一直不响应"。
3. 大比缺 once：整年刷 12 场，收益通胀。→ 教训：周期性动态事件生来就要考虑 once/年度封缄。
4. flag 键膨胀：auction-{year} 等永不清理，180 年挂 400 键。→ 教训：任何按年份生成的键都要有剪枝数（现在 3 年）。
5. UI 层"状态反直觉"：死者显示"闭关/养伤"——直觉信任崩塌。→ 教训：UI 状态必须与领域语义严格对齐（dead 分支显式）。
6. 修改覆盖事故（爸爸点名）：批量 python 替换命中旧文本 / git checkout 回滚误伤已修复文件 / 链式 replace 生成重复属性——多起"改着改着把之前修复覆盖了"。→ 教训：修改纪律——原子提交、替换三步断言、禁整文件 checkout、小步绿灯再前进（详见 AGENTS.md「修改纪律」）。
7. 模块单例纪律：MetonaSqlark 同库同 tab 一次连接（ARIA_LOCKED）；spouse 竞态防了。→ 教训：存储/稀罕资源一律单例。

五、平衡哲学（玩起来正确的普适原则）

• 修炼快感 > 真实性：宁可让"凡人百岁筑基"变成"30岁炼气、50岁筑基、百岁金丹"，不要按修真文教条拉长。
• 世代窗口：关键体验"每代 25-30 年"，一回合 1 月，推两百步就能看到"代际更替"。
• 失败必须有出口：渡劫失败只跌伤不太狠（重伤/跌落为主，陨落限高阶）；事件悬置自动压制不锁死。
• 漏斗要"花钱有去处"：后期灵石通胀是 0.1.10 才加拍卖来回收——任何资源曲线都要有消耗侧。

六、已知技术债（诚实清单）

1. realms.ts 的 expBase/expGrowth/maxRealmExp 曲线未参与计算（历史摆设，勿信勿用）。
2. GameFacade act 目录部分 act 只走 actDirect fallback（少 4 项），若未来全走 facade 需补齐 member.meditate 等。
3. npc.power 目前纯展示（不参与战斗结算）。
4. 引导任务（guide.ts）只做 UI 条，钩子目标点不完（未联动高亮/自动转跳——是"提示"不是"强制"）。
5. 行列 flag family.flag 仍在长线漂移；state.missions/missionIds 只增不减（未剪枝）。

七、如何开始修改（给下一个智能体的路径）

1. 读 AGENTS.md（红线）→ 2. 读本文件（意图）→ 3. 跑 npm test & typecheck 确认绿
→ 4. 改引擎：先改数据（data/）再改逻辑，小步跑金钟罩；改结构：注册进 clocks/plugins
→ 5. 改 UI：先改 store（revision）再改组件；纯逻辑放 game/core 可测
→ 6. 加测试：金钟罩三档不动，新增用例挂 tests/audit-fix-0.1.x.test.ts
→ 7. 提交前：npm test + typecheck + （GUI 冒烟需 WSLg 在线）+ 更新 README/PROJECT_MEMORY/AGENTS

一句话原则：先复现、再小改、后金钟罩。改坏确定性比改错玩法更危险。