thzxx
a7ee125866
- 统一时轮 GameClock：七 phase 注册制（production/aging/cultivation/missions/ events/diplomacy/epilogue） + 年首三钩子（婚配→岁贡→族簿）；advanceMonth 化作薄壳； 新增系统只注册不改本体；alive 守卫、随机序、族簿时序均与重构前逐一等价 - 金钟罩：3 枚 seed × 560 月指纹常驻（重构前后已验证同哈希；时节属有意变更后重固化） - 统一随机 RngHub：开局播种（crypto UV）、音效白噪独立流、引擎 rng 带 nextCount 审计； 全工程拔除逻辑侧 Math.random - 时节系统：春夏秋冬乘子（春田+10%/夏修+5%/秋市+5%/冬闭+8%）入生产与修炼 - 崩溃保护：advance 异常自动存『出险前』档 + 停速提示回档 - 性能预算：dev-only 单 tick>60ms 报最慢 phase - 横轴年表：十年一格大事/生殇聚合 + 春秋原年轴视图 - 测试 197→225（时钟/收集器/四季/年轴/效果全矩阵/死局链/残留防御）
4.5 KiB
4.5 KiB
AGENTS.md
仙途家族志 · Chronicle of the Immortal Clan — Electron + React + TS 家族修仙模拟器。全部 UI 与文案为中文。
命令
npm test # vitest 引擎测试（tests/*.test.ts，全部纯 Node，无 DOM/DB 依赖）
npx vitest run tests/world.test.ts # 单文件测试
npm run typecheck # tsc --noEmit（npm 会打 warn 噪音，用 npx tsc --noEmit 更干净）
npm run dev # electron-vite 热更新（开发期 origin 为 http://localhost:5173）
npm run build # 产物到 out/
npm run package # build + electron-builder（Linux 打 win 包可出产物，但未签名，Windows 上可能被 SmartScreen 静默拦截；正规发布在 Windows 侧重跑此命令）
端到端冒烟（渲染 + OPFS 数据库 + 开局推进 + 可选截图）：
npm run build
SMOKE_TEST=1 npx electron out/main/index.js --no-sandbox --disable-gpu # 退出码 0 = 全通
SMOKE_TEST=1 SMOKE_SHOTS_DIR=/tmp/opencode/shots npx electron ... # 附带 UI 截图
冒烟会写真实用户数据目录（Linux 下 ~/.config/Electron），跑完删掉该目录以免脏数据。
无显示环境（WSLg 掉线）会打印 [SMOKE-TIMEOUT] 退出码 2 而非卡死；GUI 冒烟必须在 X11/WSLg 在线时跑（引擎与存储逻辑的回归请靠 vitest，不要依赖 GUI）。另注意：npx electron 可能拉取新版 electron 缓存版（与本仓库 33.x 不同），二进制安装以 node_modules/electron 为准。
环境坑
- npm 12 拦截 postinstall：首次安装后须
npm install-scripts approve electron esbuild，否则 Electron 二进制缺失。 npm rebuild electron esbuild会删掉node_modules/electron/dist/electron（Linux 二进制），修复：ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ node node_modules/electron/install.js- 私有 registry 的
_authtoken 只在用户级~/.npmrc；项目.npmrc只保留 registry 映射，不要把 token 写进仓库。 - Linux 无 emoji 字体：所有图标一律用汉字印章字符（renderer/ui/styles.css 的
.s-icon/.res-icon/.bld-icon），不要引入 emoji。
架构要点
src/renderer/game/：纯 TS 游戏引擎（无 React/DOM import），可被 vitest 直接测试；types/domain.ts是全量领域类型，改状态结构先看它。- 统一时轮
core/clock.ts：月度 phase（production/aging/cultivation/missions/events/diplomacy/epilogue）+ 年首钩子均注册于engine/clocks.ts。新增系统 = 注册一行，禁止手改advanceMonth本体。 - 统一随机
core/rng.ts：引擎只经World.rng（含nextCount审计）；UI 播种用RngHub.rollSeed()、音效白噪用RngHub.audioNoise01()，不要在逻辑里引入 Math.random()。 - 金钟罩
tests/clock.test.ts：3 枚固定 seed 560 月指纹常驻。任何改动若破坏确定性立即红；有意变更时序时三枚指纹一并小重算并在注释注明原因。 src/renderer/ui/：React + zustand（ui/store.ts）。World 的 game state 是 mutable，advance 后revision++触发重渲染；订阅revision是面板刷新惯例。- 引擎 = 种子随机数（sfc32，
core/rng.ts）+ 不可变快照存state.rng，同 seed 全程可重放（tests/world.test.ts 有确定性用例，改任何 tick 顺序都要保证仍然确定性）。 - 建档开头成员 id 硬编码
x1~x5，tests 依赖。
MetonaSqlark（@metona-team/metona-sqlark 0.7.4）陷阱
- SQL 方言为自有实现（不是 SQLite）：建表列类型写
string|number|boolean|date|json，不是INTEGER/TEXT；不支持INSERT OR REPLACE、ON CONFLICT、rowid——用「SELECT 判断 → UPDATE/INSERT」或直接DELETE+INSERT。 - aria 引擎同库一个 tab 只能建一次连接（Web Locks →
ARIA_LOCKED）：存取必须走game/storage/db.ts的单例getSaveSlot(slot)/getSlotManager()，禁止每次new SaveSlot/new SlotManager。 - 数据在浏览器 OPFS（renderer 内），main 进程无 DB 逻辑；开发与打包后的 origin 不同，两环境存档不互通。
- 存储层通过
SaveDbDriver抽象（storage/slots.ts），node 环境下无 OPFS，测试只覆盖引擎不覆盖 DB。
工作流约定
- 提交前：
npm test+npm run typecheck必须绿（改存储/SQL 后再跑一次冒烟）。 - 平衡数值集中在
game/data/（realms/pacing/buildings/events...），调平衡不改引擎流程。 - 发布产物
release/、out/均已 gitignore，勿入库。