From 8f1f8d48ce97a6f2fefc0347acdcb57c3947c306 Mon Sep 17 00:00:00 2001
From: thzxx <1440196015@qq.com>
Date: Thu, 10 Sep 2026 23:46:51 +0800
Subject: [PATCH] =?UTF-8?q?chore:=20=E7=89=88=E6=9C=AC=E5=8F=B7=E5=8D=87?=
=?UTF-8?q?=E7=BA=A7=E5=88=B0=200.1.37=EF=BC=88package.json/AGENTS.md/MOD?=
=?UTF-8?q?=5FGUIDE.md/ApiFacade/storeHelper/SettingsPanel/slots/=E6=B5=8B?=
=?UTF-8?q?=E8=AF=95=E6=96=AD=E8=A8=80=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
AGENTS.md | 2 +-
docs/MOD_GUIDE.md | 43 ++++++++++++++++++-
package.json | 2 +-
src/renderer/game/engine/runtime/ApiFacade.ts | 2 +-
src/renderer/game/storage/slots.ts | 2 +-
src/renderer/ui/panels/SettingsPanel.tsx | 2 +-
src/renderer/ui/storeHelper.ts | 2 +-
tests/facade-registry.test.ts | 2 +-
8 files changed, 48 insertions(+), 9 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 3412d23..e5edd0a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,7 @@
# AGENTS.md
仙途家族志 · Chronicle of the Immortal Clan — Electron + React + TS 家族修仙模拟器。全部 UI 与文案为中文。
-当前版本 **0.1.33**（《闭环·流光》：物品生态闭环（符箓生效/僵尸物品归位/灾年入产）+ 引擎止血 15 项 + UI 动效打磨（Modal 过渡/停帧节能/季节对齐）+ 测试 5230）。
+当前版本 **0.1.37**（《天人感应·因果织锦》：功德因果系统 + 飞升三阶段试炼 + 种子派生世界奇观 + MOD 扩展口（奇观类型注册/worldNum 白名单/因果事件/飞升前缀保护）+ 测试 7040）。
## 命令
diff --git a/docs/MOD_GUIDE.md b/docs/MOD_GUIDE.md
index 0d2eea0..7332047 100644
--- a/docs/MOD_GUIDE.md
+++ b/docs/MOD_GUIDE.md
@@ -131,6 +131,7 @@ macOS: ~/Library/Application Support/Electron/mods/
| 内容面 | `aspirations` | §9.5 | 志向（修为/战斗/市贸/产田/生育/声望） | 摘除 |
| 内容面 | `formations` | §9.5 | 阵型（攻击/防御/撤退伤） | 摘除 |
| 内容面 | `traits` | §9.5 | 性格（修为/突破/战力/魅力/售价加成） | 摘除 |
+| 内容面 | `wonders` | §9.7 | 世界奇观类型（零 rng 种子派生选取——自定义奇观加入年首判定池） | 摘除 |
| 微调 | `patch` | §9.6 | 对**已存在**表项改数值（mult 或 add）——不改结构只改数 | 按插件归属复原 |
### 2.3 一个"五脏俱全"的示意壳（啃编排用）
@@ -158,6 +159,7 @@ macOS: ~/Library/Application Support/Electron/mods/
"aspirations": [ /* §9.5 */ ],
"formations": [ /* §9.5 */ ],
"traits": [ /* §9.5 */ ],
+ "wonders": [ /* §9.7 */ ],
"patch": [ /* §9.6 */ ]
}
}
@@ -943,11 +945,48 @@ macOS: ~/Library/Application Support/Electron/mods/
---
-**一句话总结**：MOD = 一个有 `data` 字段的 JSON。事件管"剧情"、模板管"新家族"、词库管"名字概率"、灾因管"灾年种类"、丹方铸器管"炼丹造兵"、worldNum 管"世界脾性"、内容面七口管"新物品/功法/建筑/职事/志向/阵型/性格"、patch 管"已有表项微调"。装/卸/导出全在设置页，读档重装全自动。去写吧——这个世界等你的素材。
+### 9.7 世界奇观类型扩展（wonders） · 0.1.37 新增
+
+0.1.37 引入**世界奇观**——年首种子派生判定（零 rng 消耗），4 种内置奇观：灵气涌潮 / 古遗迹现身 / 天降祥瑞 / 灵脉枯竭。
+
+MOD 可以注册**自定义奇观类型**，加入年首种子派生选取池：
+
+```jsonc
+"wonders": [
+ {
+ "kind": "star_fall", // 唯一 id（不可与内置 tide_surge/ancient_ruin/heaven_bless/qi_wane 冲突）
+ "name": "星陨天落", // 中文名称
+ "desc": "天外陨星坠落——灵气激荡，宝材出世。", // 描述文本
+ "duration": 12, // 持续月数（0 = 一次性）
+ "effect": "tide_up", // 持续效果：tide_up=灵气增益 / tide_down=灵气衰减 / none=无
+ "oneshot": "loot" // 一次性效果：bless=灾年消弭+声望+5 / loot=随机资源获取 / none=无
+ }
+]
+```
+
+**字段说明**：
+
+| 字段 | 必填 | 取值 | 说明 |
+|------|------|------|------|
+| `kind` | ✓ | 唯一字符串 | 奇观类型 id（与内置+已注册不冲突） |
+| `name` | ✗ | 字符串 | 中文名（缺省"异变"） |
+| `desc` | ✗ | 字符串 | 描述（缺省"天地异变，灵机暗涌。"） |
+| `duration` | ✗ | 0~60 | 持续月数（缺省 0=一次性） |
+| `effect` | ✗ | `tide_up`/`tide_down`/`none` | 持续月度效果（缺省 `none`） |
+| `oneshot` | ✗ | `bless`/`loot`/`none` | 出现时一次性效果（缺省 `none`） |
+
+> **零 rng 保证**：奇观判定使用种子哈希派生（`seed ^ year ^ npcSuccessions`），不消耗 `rng.next()` 序列——金钟罩确定性不受影响。
+> **因果事件**：事件选项 `eff.karma` 可正可负——MOD 事件天然支持因果变动（无需额外口）。
+> **worldNum 白名单**：`wonderChance`（0.08）/ `karmaDecayRate`（0.1）/ `karmaHighThreshold`（30）/ `karmaLowThreshold`（-20）可经 `data.worldNum` 覆写。
+
+---
+
+**一句话总结**：MOD = 一个有 `data` 字段的 JSON。事件管"剧情"、模板管"新家族"、词库管"名字概率"、灾因管"灾年种类"、丹方铸器管"炼丹造兵"、worldNum 管"世界脾性"、内容面八口管"新物品/功法/建筑/职事/志向/阵型/性格/奇观"、patch 管"已有表项微调"。装/卸/导出全在设置页，读档重装全自动。去写吧——这个世界等你的素材。
> 0.1.32 玩注：资源循环已是六类生态（资源/材料/丹药/符箓/灵酿/兵器），新物产入池即参与世界呼吸与 NPC 贸易——写材料口别怕世界吃不进去。
> 0.1.33 闭环注：符箓开战即耗（风符×1.12/山符×1.15+减伤——零 rng 结算），灵酿渡劫伤后自动回气；丹方/铸器产出物 ALL 必须先在物品表立名（否则幽灵物品不可见不可卖）。
> 0.1.34 功法注：四流派效果 crit/guard/trib/secret 全 optional——缺省零行为，金钟罩安全；元素时节共鸣 4 季同频（土系恒应）。
> 0.1.35 涤荡注：无存档迁移（游戏未发布——旧档随版本演进失效属预期）；`patch` 层按插件归属回滚；validate 覆盖 §12 全部规则。
+> 0.1.37 因果奇观注：奇观零 rng（种子派生选取池含 MOD 扩展）；`eff.karma` 天然支持；`wonderChance`/`karmaDecayRate`/`karmaHighThreshold`/`karmaLowThreshold` 可经 worldNum 覆写；飞升事件 `ev-ascension-*` 前缀保护防劫持。
-⚔️ 本文档随游戏版本更新（0.1.36）。字段若有新增，此处先行。
+⚔️ 本文档随游戏版本更新（0.1.37）。字段若有新增，此处先行。
diff --git a/package.json b/package.json
index 1d1cf85..fa56726 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "chronicle-of-the-immortal-clan",
"productName": "仙途家族志",
- "version": "0.1.36",
+ "version": "0.1.37",
"description": "修仙 · 家族 · 经营 · 战斗 模拟器",
"main": "./out/main/index.js",
"author": "MetonaTeam",
diff --git a/src/renderer/game/engine/runtime/ApiFacade.ts b/src/renderer/game/engine/runtime/ApiFacade.ts
index a64f696..ddb6073 100644
--- a/src/renderer/game/engine/runtime/ApiFacade.ts
+++ b/src/renderer/game/engine/runtime/ApiFacade.ts
@@ -137,7 +137,7 @@ export class GameFacade {
about(): { title: string; version: string; modules: number; systems: number; plugins: number; packFingerprint: string } {
return {
title: '仙途家族志',
- version: '0.1.36',
+ version: '0.1.37',
modules: this.world.systemList().length,
systems: this.world.systemList().filter((s) => s.enabled).length,
plugins: this.world.pluginList().length,
diff --git a/src/renderer/game/storage/slots.ts b/src/renderer/game/storage/slots.ts
index d65ed93..c5f92b9 100644
--- a/src/renderer/game/storage/slots.ts
+++ b/src/renderer/game/storage/slots.ts
@@ -1,7 +1,7 @@
import { GameState, SaveMeta, SnapshotMeta, Id } from '../types/domain'
import { validateLoadedState, exportEnvelope, parseImportEnvelope } from './migrate'
-const GAME_VERSION = '0.1.36'
+const GAME_VERSION = '0.1.37'
const DB_PREFIX = 'cotyc-save-'
let seqCounter = 0
diff --git a/src/renderer/ui/panels/SettingsPanel.tsx b/src/renderer/ui/panels/SettingsPanel.tsx
index ba131b8..60c20b2 100644
--- a/src/renderer/ui/panels/SettingsPanel.tsx
+++ b/src/renderer/ui/panels/SettingsPanel.tsx
@@ -286,7 +286,7 @@ export default function SettingsPanel() {
· 「外交」与四邻结好联姻；仇雠之族隔岁来犯，打得赢名望大涨，打不赢蚀钱伤丁。
· 「史书」自动记述繁华与凋零——百年之后，后人翻开这一卷家族志，见代代薪火、历历雪泥。
- 版本 0.1.36 · Chronicle of the Immortal Clan
+ 版本 0.1.37 · Chronicle of the Immortal Clan
)
diff --git a/src/renderer/ui/storeHelper.ts b/src/renderer/ui/storeHelper.ts
index 5c62445..5ea35f9 100644
--- a/src/renderer/ui/storeHelper.ts
+++ b/src/renderer/ui/storeHelper.ts
@@ -14,7 +14,7 @@ export function metaFromState(state: GameState, slot: number): SaveMeta {
members: alive,
reputation: state.family.reputation,
updatedAt: new Date().toISOString(),
- version: '0.1.36'
+ version: '0.1.37'
}
}
diff --git a/tests/facade-registry.test.ts b/tests/facade-registry.test.ts
index 8263faa..52a7c7c 100644
--- a/tests/facade-registry.test.ts
+++ b/tests/facade-registry.test.ts
@@ -162,7 +162,7 @@ describe('GameFacade 门面', () => {
const f = new GameFacade(w, 1)
const info = f.about()
expect(info.title).toBe('仙途家族志')
- expect(info.version).toContain('0.1.36')
+ expect(info.version).toContain('0.1.37')
expect(info.modules).toBeGreaterThanOrEqual(11)
expect(info.systems).toBeGreaterThan(0)
expect(info.plugins).toBeGreaterThanOrEqual(3)