docs: 沉淀项目记忆（AGENTS 数值红线 + PROJECT_MEMORY 档案 + README 沿革）
- AGENTS.md：新增「数值基调（0.1.10 重建后，勿当 bug 调回去）」红线段—— pacing 因子唯一生效、月率公式、寿元梯度、渡劫三选、事件优先级、flag 剪枝 - docs/PROJECT_MEMORY.md：项目叙事记忆新档案——设计哲学/版本为什么/架构决策/ 踩坑六记/平衡哲学/已知技术债/开始修改路径 - README：版本沿革补 0.1.10/0.1.11，测试规模 923+
This commit is contained in:
@@ -57,6 +57,15 @@ SMOKE_TEST=1 SMOKE_SHOTS_DIR=/tmp/opencode/shots npx electron ... # 附
|
||||
- 数据在浏览器 OPFS（renderer 内），main 进程无 DB 逻辑；开发与打包后的 origin 不同，两环境存档不互通。
|
||||
- 存储层通过 `SaveDbDriver` 抽象（`storage/slots.ts`），node 环境下无 OPFS，测试只覆盖引擎不覆盖 DB。
|
||||
|
||||
## 数值基调（0.1.10 重建后，勿当 bug 调回去）
|
||||
|
||||
- **pacing.ts 的 MAJOR_RATE 是进度唯一生效因子**（qi 2.2、foundation 1.4、core 0.95、nascent 0.68、spirit 0.48）；`realms.ts` 的 `expBase/expGrowth/maxRealmExp` 曲线**未参与计算**（历史摆设，勿以它反推）。
|
||||
- 月率 base = `1.0 + perception*0.18`；65 岁起 ×0.72 衰减、8 岁以下 ×0.65（圣者护族 60+ 高境界者存在时乘 1.3）。
|
||||
- 寿元：75/150/220/340/520/850（凡人→化神，0.1.10 放宽的梯度）。
|
||||
- 大境界晋升走**渡劫事件三选**（硬渡/护法/压制）；玩家 12 月不应会**自动压制一年**（防挂机软锁，events.ts 计数 `tribPendingMonths`）。
|
||||
- 周期事件优先级：命运（百年/飞升）> 大比 > 传薪 > 拍卖 > 岁祷 > 回声；大比有 `once`，一年一届。
|
||||
- `family.flag` 年份键（auction-/prayerDone-/echoDone-/recruitDone-）每 tick 剪 3 年前旧键。
|
||||
|
||||
## 工作流约定
|
||||
|
||||
- 提交前：`npm test` + `npm run typecheck` 必须绿（改存储/SQL 后再跑一次冒烟）。
|
||||
|
||||
@@ -14,7 +14,7 @@ npm run dev # 开发模式（热更新）
|
||||
npm run verify # 发布验收哨兵：vitest + typecheck + build
|
||||
npm run verify:package # 附打包预览（electron-builder）
|
||||
npm run package # 直接打包（Windows 需在 Windows 侧执行）
|
||||
npm test # 仅测试（861+ 用例）
|
||||
npm test # 仅测试（923+ 用例）
|
||||
```
|
||||
|
||||
## 架构一览
|
||||
@@ -58,3 +58,5 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存档导
|
||||
| 0.1.7 | 仙门之钥（门面/能力注册表/数据包/开发者面板） |
|
||||
| 0.1.8 | 万物皆是插件 + 全应用审计（60+ 缺陷歼灭） |
|
||||
| 0.1.9 | 百年报告 + 存档迁移 v2 + 战斗阵型 + 冬祷 + 发布哨兵 |
|
||||
| 0.1.10 | 长线决断（数值重建：修炼提速/寿元放宽/渡劫修复 + 拍卖/传薪/护族） |
|
||||
| 0.1.11 | 全源码审计缺陷歼灭 + UX 打磨（警讯徽章/首启引导/格式化） |
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
# 项目记忆 · 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
|
||||
```
|
||||
|
||||
**一句话原则**：先复现、再小改、后金钟罩。改坏确定性比改错玩法更危险。
|
||||
Reference in New Issue
Block a user