MetonaTeam/ChronicleOfTheImmortalClan
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: AGENTS 同步 0.1.32（金钟罩注释修正 + p 文件教训入修改纪律 + 物品六类生态纪律）

Browse Source
This commit is contained in:
thzxx
2026-08-23 21:10:04 +08:00
parent 9fbbe16dd8
commit fa477fb3ef
1 changed files with 3 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+3 -2
View File
@@ -61,7 +61,7 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
- **插件架构**（0.1.8 起，路径已迁 engine/runtime|kernel）：`kernel/plugin.ts` 协议、`runtime/pluginManager.ts` 安装管线（依赖校验/异常回滚/追踪型上下文——注销时钩子全摘）、`plugin-bootstrap.ts` 三核心插件（core-systems/core-data/core-events protected）。事件多池 `world.eventPools`；**findEvent 必须带 world 参数查池**。能力卡 12 张经 `viaCap` 注册；tournament/tribulation/apprentice/season 四卡各自内部检查 `w.sysEnabled`（无独立钩子）。 - **插件架构**（0.1.8 起，路径已迁 engine/runtime|kernel）：`kernel/plugin.ts` 协议、`runtime/pluginManager.ts` 安装管线（依赖校验/异常回滚/追踪型上下文——注销时钩子全摘）、`plugin-bootstrap.ts` 三核心插件（core-systems/core-data/core-events protected）。事件多池 `world.eventPools`；**findEvent 必须带 world 参数查池**。能力卡 12 张经 `viaCap` 注册；tournament/tribulation/apprentice/season 四卡各自内部检查 `w.sysEnabled`（无独立钩子）。
- **MOD 红线（0.1.26 规范）**：MOD 只含 JSON 零脚本（`docs/MOD_GUIDE.md`）；**禁止新增 rng 消耗**（全局随机序列）；不改核心时序（扩展走五口：事件池/模板/词库/灾因/配方）；`modPreflight`+`validateMod` 先行（id 冲突用 `findEvent` 权威检测）；MOD 只影响**新开档**世界（老档世界变形成档记录）；MOD 状态随 `state.plugins` 持久化（对应 `worldGen.npcs` 落档保证读档永稳）。 - **MOD 红线（0.1.26 规范）**：MOD 只含 JSON 零脚本（`docs/MOD_GUIDE.md`）；**禁止新增 rng 消耗**（全局随机序列）；不改核心时序（扩展走五口：事件池/模板/词库/灾因/配方）；`modPreflight`+`validateMod` 先行（id 冲突用 `findEvent` 权威检测）；MOD 只影响**新开档**世界（老档世界变形成档记录）；MOD 状态随 `state.plugins` 持久化（对应 `worldGen.npcs` 落档保证读档永稳）。
- **门面**：`runtime/ApiFacade.ts` GameFacade（act 24 项/query 6 类/subscribe 退订协议/about）；**UI 面板事实走 world 直调**（act 为测试/自动化通道），`actDirect` 与 ACT_CATALOG 语义对齐（0.1.20 补齐全 24 项）；store 的 `facade` 必须在 openState/startNewGame 赋值。 - **门面**：`runtime/ApiFacade.ts` GameFacade（act 24 项/query 6 类/subscribe 退订协议/about）；**UI 面板事实走 world 直调**（act 为测试/自动化通道），`actDirect` 与 ACT_CATALOG 语义对齐（0.1.20 补齐全 24 项）；store 的 `facade` 必须在 openState/startNewGame 赋值。
- **金钟罩（双基线）**：`tests/clock.test.ts` 的 `GOLDEN`（直调冻结世界）+ `GOLDEN_RESOLVED`（自动 resolve 长跑"现实"世界），各 3 seed × 三档月数（560/1200/2160）共 18 值。当前为 **0.1.28 基线**（第三轮审计指纹补盲后固化；0.1.25/0.1.26 曾零漂，0.1.27/0.1.28 受控变更重算）。指纹 `tests/fingerprint.helper.ts` 含全世界轴（era/stance/prosperity/relationsWithOthers/calamity/pendingEvent/eventQueue/worldAnnals/**worldGen 摘要/sagaAnnals/distress/declineYears 汇总**——0.1.27 生灭/世鉴路径真实锁定）。**有意变更时序/数值时**：指纹一并重算并在注释注明原因。 - **金钟罩（双基线）**：`tests/clock.test.ts` 的 `GOLDEN`（直调冻结世界）+ `GOLDEN_RESOLVED`（自动 resolve 长跑"现实"世界），各 3 seed × 三档月数（560/1200/2160）共 18 值。当前为 **0.1.32 基线**（0.1.25/0.1.26/0.1.31 零漂；0.1.27/0.1.28/0.1.29/0.1.30/0.1.32 受控变更重算）。指纹 `tests/fingerprint.helper.ts` 含全世界轴（era/stance/prosperity/relationsWithOthers/calamity/pendingEvent/eventQueue/worldAnnals/**worldGen 摘要/sagaAnnals/distress/declineYears 汇总**——0.1.27 生灭/世鉴路径真实锁定）。**有意变更时序/数值时**：指纹一并重算并在注释注明原因。
## 世界自演进模型（0.1.14 sim/ 层，改数值勿动流程） ## 世界自演进模型（0.1.14 sim/ 层，改数值勿动流程）
@@ -73,6 +73,7 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
- **家族生灭**：`npcDyn.declineYears`（power<58 且 景气<38 连续 8 年）→ 覆灭（最强邻分食+史官广播）；家族数 < 开局目标（4~8）年首新贵补位（`greatNewbornChance`，乱世×2）。 - **家族生灭**：`npcDyn.declineYears`（power<58 且 景气<38 连续 8 年）→ 覆灭（最强邻分食+史官广播）；家族数 < 开局目标（4~8）年首新贵补位（`greatNewbornChance`，乱世×2）。
- **世界种子**（0.1.24）：`sim/worldgen.ts` `generateWorld(seed)`——NPC 4~8 家随机/初始关系网（1-2 世仇+1 盟友）/开局 era/市场 ±15% 偏移；**独立派生 rng**（`seed::worldgen`，World.rng 主序列零消耗）；`state.worldGen` 摘要落档（含 npcs defs——读档幂等重注册，存档世界永稳）。 - **世界种子**（0.1.24）：`sim/worldgen.ts` `generateWorld(seed)`——NPC 4~8 家随机/初始关系网（1-2 世仇+1 盟友）/开局 era/市场 ±15% 偏移；**独立派生 rng**（`seed::worldgen`，World.rng 主序列零消耗）；`state.worldGen` 摘要落档（含 npcs defs——读档幂等重注册，存档世界永稳）。
- **天下史表**：`worldSim.worldAnnals[]`（十年一鉴 80 页留档，免 newsFeed 裁剪丢失）。 - **天下史表**：`worldSim.worldAnnals[]`（十年一鉴 80 页留档，免 newsFeed 裁剪丢失）。
- **物品六类生态纪律**（0.1.32）：resource/material/pill/talisman/brew/artifact——**新资源必须四同步**（ITEMS 定义 + POOL_BASE + MARKET_IDS + worldgen marketOffset）才入世界循环（呼吸/NPC 贸易/灾年超卖）；消耗类物品效果（符箓/灵酿）**零 rng 消耗**（自动消耗实现——金钟罩安全）。
## MetonaSqlark（@metona-team/metona-sqlark 0.7.4）陷阱 ## MetonaSqlark（@metona-team/metona-sqlark 0.7.4）陷阱
@@ -98,7 +99,7 @@ src/main/ Electron 主进程（app:// 协议 + IPC 存
**硬性规则**： **硬性规则**：
1. **改动前**：`git status` 确认工作区干净（或先提交当前成果，原子提交，一功一提交）。 1. **改动前**：`git status` 确认工作区干净（或先提交当前成果，原子提交，一功一提交）。
2. **改动中**：批量替换一律用「先 assert 旧文本存在 → 替换 → 再全局 grep 断言新文本唯一」三步；禁止无检查的 sed/python 盲替。 2. **改动中**：批量替换一律用「先 assert 旧文本存在 → 替换 → 再全局 grep 断言新文本唯一」三步；禁止无检查的 sed/python 盲替。**写盘脚本严禁惰性路径**（0.1.32 教训：`open('p','w')` 撇笔把模块源码碎片写进根目录并被 git add 入库）——写文件必须用**显式路径变量**且写后立即 `git status` 检查工作区异常新文件。
3. **禁止 `git checkout -- <file>` / 整文件回滚**（这是历史事故元凶）。确需回滚时：`git show HEAD:<file> > /tmp/bak` 手动 diff 恢复，恢复后跑全量测试确认无伤。 3. **禁止 `git checkout -- <file>` / 整文件回滚**（这是历史事故元凶）。确需回滚时：`git show HEAD:<file> > /tmp/bak` 手动 diff 恢复，恢复后跑全量测试确认无伤。
4. **优先小步快跑**：每个功能块改完立即 `npm test`（引擎）或 `tsc`（UI 类型），绿了再动下一处——绝不在错误状态上加新修改。 4. **优先小步快跑**：每个功能块改完立即 `npm test`（引擎）或 `tsc`（UI 类型），绿了再动下一处——绝不在错误状态上加新修改。
5. **高危文件白名单**（world.ts / events.ts / store.ts / styles.css / cultivation.ts / **WorldSim.ts / worldsim-data.ts**）改动后必须 `git diff --stat` 核对改动面与预期一致。 5. **高危文件白名单**（world.ts / events.ts / store.ts / styles.css / cultivation.ts / **WorldSim.ts / worldsim-data.ts**）改动后必须 `git diff --stat` 核对改动面与预期一致。