# 项目记忆 · 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. **模块单例纪律**：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
```

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