# 项目记忆 · 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↔景气**双向闭环**（自演进最高形态）；渲染管线修 |

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

### 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. 线程定论（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 节流必须真实接线；冗余表用增量写**。
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 恒真已注册，实际不可关）——如需可关需重构。

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

```
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 + typecheck + （GUI 冒烟需 WSLg 在线）+ 更新三份文档
```

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