# 仙途家族志 · Chronicle of the Immortal Clan

修仙 × 家族 × 经营 × 战斗的家族模拟器（Electron + React + TypeScript + MetonaSqlark）。

一座庄园、一家修士、四邻势力，随年月流转：族人修炼突破、建筑产出、探秘寻宝、婚丧嫁娶；
仇家犯境则结阵应战；百年之际，望气定鼎，春秋原上写下一卷族史。
**世界也在自演进**：市场有真库存与供需呼吸，NPC 有战略姿态与恩怨网，时代有盛世乱世的大势流转——天下兴衰与家族命运互为因果。

## 快速开始

```bash
npm install                # 依赖（含 git.metona.cn 私有 registry，token 在用户级 ~/.npmrc）
npm install-scripts approve electron esbuild   # npm12 首装时必须（Electron 二进制）
npm run dev                # 开发模式（热更新）
npm test                   # 引擎测试（108 套件 / 7058 用例，纯 Node 无 GUI）
npm run build              # 产物到 out/
npm run package            # 打包（Windows 需在 Windows 侧执行）
```

端到端冒烟（渲染 + OPFS + 开局推进 + 可选截图）：见 `AGENTS.md`「命令」。

## 架构一览

```
src/renderer/game/                纯 TS 引擎（无 React/DOM，vitest 直测；单线程，实测 0.05ms/tick）
  engine/GameEngine.ts            唯一门面：advance / restore / engineFromSnapshot / about / resolvePending
  engine/kernel/                  Kernel（Clock+Rng 三合一）+ clock / rng(RngHub) / plugin / guide / urgency...
  engine/runtime/                 World（大对象+normalize+bus 转发）· clocks（时轮注册）· ApiFacade（GameFacade）
                                  Systems/（生产/修炼/任务/事件/外交/婚育/渡劫/大比/寿元/战斗）
                                  capabilities（12 能力卡）· pluginManager（插件管线）
  engine/sim/                     WorldSim（世界自进化）· worldsim-data（数值唯一权威）· Market（行情/买卖）
  engine/narrative/               族谱/传记/定鼎/年轴/百年报告
  data/                           balance 表 + DataPackRegistry（PILL_RECIPES / FORGE_RECIPES / ERA_CONF）
  storage/                        db(MetonaSqlark 单例) · slots(槽+快照) · migrate(CURRENT_SCHEMA=2，normalize 即迁移)
  types/domain.ts                 全量领域类型（改状态结构先看它）
src/renderer/ui/                  React + zustand（store.ts 主状态；面板按 tab 挂载；LogFeed 精订阅）
src/main/                         Electron 主进程（app:// 协议 + IPC 存档导出/导入）
```

设计文档见 `AGENTS.md`（环境坑 / 架构红线 / 引擎纪律 / 金钟罩双基线 / 修改纪律）；
**MOD 作者守则**见 `docs/MOD_GUIDE.md`（规范：命名/schema/五数据口/安全红线）。

## 守护机制

- **双金钟罩**：`tests/clock.test.ts` 的 `GOLDEN`（直调冻结世界）+ `GOLDEN_RESOLVED`（自动 resolve 长跑“现实”世界），各 3 固定 seed × 560/1200/2160 月（47/100/180 年）= 18 指纹；指纹含全世界轴（era/stance/prosperity/关系网/事件闸）；**0.1.41 基线**。有意变更时序需受控更新并注明。
- **事件闸**：pending 唯一入口 `fire(w,id,priority)`——高优（raid/渡劫/大比）可顶替被占者，被顶替者入队下月兑现；`applyEventChoice` 前置校验防陈旧 Modal 二次结算。
- **插件化**：万物皆是插件（系统/数据包/事件池），三核心插件 protected 常驻；示例见 tests/helpers/examplePlugin.ts。
- **可回放**：种子随机（sfc32，引擎域零 Math.random）+ 快照回放保真（restore 重建内核+回置 rng）。
- **审计五轮**：0.1.15（引擎 P0 歼灭）/ 0.1.20（事件闸·市场黑洞·双金钟罩）/ 0.1.28（稳石：词库回滚·新贵落档·校验接生产·bundle 闭环·指纹补盲）/ 0.1.29（续命：续代断链·敌强度相对化·权重防洪）/ **0.1.35（荡涤：17 缺陷歼灭·兼容层铲除·validateLoadedState 替代迁移）**。
- **测试规模**：**108 套件 / 7058 例**（矩阵域：随机序列/世界生成/市场实体化/事件闸/数据表全量/插件 MOD 组合/省级矩阵等——语义真实，无刷水）。

## 打包产物

- `npm run package` → out/（构建）+ release/（安装包）
- 图标资源 resources/icon.png|ico —— electron-builder 自动使用
- 注意：WSL/Linux 交叉打 win 包可行但未签名，正规发布请用 Windows 侧重跑

## 版本沿革（0.1.0 → 0.1.41）

| 版本 | 主题 |
|---|---|
| 0.1.0-0.1.11 | 核心循环 → 插件架构 → 审计三连（详见 docs/PROJECT_MEMORY.md） |
| 0.1.12 | 金碧山河（SVG 素材 + 动效系统 + 舞美重装） |
| 0.1.13 | 交付与回档（工艺/界面修复 + UI 存储直连回档） |
| 0.1.14 | 大重构：GameEngine 门面 + Kernel 三合一 + WorldSim 世界自进化（五大闭环） |
| 0.1.15 | 深度审计加固（7 P0 + 20+ P1 歼灭；restore 双注册/引擎锁死等） |
| 0.1.16 | 资源闭环 × 世情入味（修为耗草/炼丹概率化/铸器/灵脉收益/NPC 战力/灾变落效） |
| 0.1.17 | 天下为市——市场实体化（真库存/供需呼吸/NPC 上桌/玩家回写）+ 战争伤骨 + 关系网 |
| 0.1.18 | 时代绘卷（世纪弧 era/NPC 景气/蝴蝶效应/十年鉴）+ 特效入引擎（onFx 语义出口） |
| 0.1.19 | 八方风雨（NPC 战略姿态/超卖潮/盟约连坐/干预天下）+ 孤立系统归并（FxGate/音效/兜底） |
| 0.1.20 | 万世无谬（第二轮全量审计：事件闸优先级/era 延续/潮汐符号/弱锚定/双金钟罩） |
| 0.1.21 | 大势流转（线程定论 0.05ms、era↔景气双向闭环、世界史表、渲染管线修复） |
| 0.1.22 | 灯下春秋（Modal 全走 body Portal / 年报不打断自动速度 / 姓氏假功能修复） |
| 0.1.23 | 生灭千秋（家族覆灭/新贵补位、秘境回池、WorldSnapshot、插件持久化/双闸/自动回滚） |
| 0.1.24 | 寰宇初构（世界种子生成器：NPC 4~8 家随机/开局恩怨/era/市场偏移；插件的时轮锚点/模板注入） |
| 0.1.25 | 乾坤一统（MOD 系统首版：userData/mods 扫描/解析/安装/持久化 + worldGen 存档永稳修复） |
| 0.1.26 | 墨规清辉（MOD 规范范式：MOD_GUIDE/validateMod/灾因注册表 + 页面文本提亮可读性） |
| 0.1.27 | 活水长流（生灭可达化：180 年实测驱动——门槛/era 调制增长/顶峰衰 + 修为↔市场回环 + 世鉴 50/100 年 + 测试 2000） |
| 0.1.28 | 稳石（第三轮全量审计歼灭：词库回滚/新贵落档/校验接生产/bundle 导入/救济正道/快讯解锁 + 指纹补盲） |
| 0.1.29 | 续命（第四轮全量审计歼灭：续代断链修复/敌强度相对化/权重防垄断/启用过滤/并发存档修复） |
| 0.1.30 | 兼济（人口-世界成本闭环 + 世界关注度（匹夫无罪）+ 内置 MOD 仓库/冲突矩阵/预览 + 测试 3006） |
| 0.1.31 | 万物皆可 MOD（内容面七口：物品/功法/建筑（表达式 DSL）/职事/志向/阵型/性格 + kind 分类 + ERA_DURA/REGION_TIDE 聚合 + 测试 4006） |
| 0.1.32 | 万宝琳琅（物品六类化 + 新材料七种入市 + 符箓武备/灵酿回气 + 生产泛化 + 测试 5009） |
| 0.1.33 | 闭环·流光（物品生态闭环（符箓生效/僵尸物品归位/灾年入产）+ 引擎止血 15 项 + UI 动效打磨 + 测试 5230） |
| 0.1.34 | 万象归元（功法流派化×元素时节共鸣 + 世界自演化二层 + 插件卡 12→14 + MOD 功法效果口+patch 数值层 + 测试 6000） |
| 0.1.35 | 荡涤·向新（17 缺陷歼灭 + 兼容层整体铲除 + validateLoadedState 替代迁移 + 测试 7000） |
| 0.1.36 | CSP 根因（arith.ts 纯解析器全量替换 Function() + ErrorBoundary 防白屏 + dev:web 浏览器通道） |
| 0.1.37 | 天人感应（因果系统 karma + 飞升试炼三阶段 + 世界奇观种子派生 + 测试 7030） |
| 0.1.38 | 存档根治·石碑重刻（OPFS 探测+自动降级 IndexedDB + 回读校验 + 诊断面板 + driver.open 锁死修复） |
| 0.1.39 | 淬体·洗髓（missionIds 根治 + chronicle 智能裁剪 + worldsim 双闸守卫 + purgeNpc 僵尸定义清理 + MemberCard memo 化 + 飞升视觉强化 + 测试 7058） |
| 0.1.40 | 天命·裂痕（天命议题系统 20 条 5 类种子派生选取 + NPC 宗主更替四模式 + NPC 势力分裂 + 灰烬重生新贵补位 + 建筑专精系统 extra×1.5 + UI memo 化 4 处 + 天下大事记叙事层 saga.ts + WorldPanel/LegacyPanel 大事记展示） |
| 0.1.41 | 天命·兑现（天命 flag 全量接线 15+ 项即时兑现 + NPC 演化种子派生零主 rng 消耗 + pushNews/purgeNpc 确定性修复 + 族史卷叙事层 chronicle-scroll.ts + 时效 flag 自动清理 + UI 建筑专精加成预览 + LegacyPanel 族史卷视图） |

详见：`docs/PROJECT_MEMORY.md`（设计哲学与每个迭代的"为什么"）。