From d8d34fcb74880f182dfd89af1d00f483ae6bb9b7 Mon Sep 17 00:00:00 2001
From: thzxx <1440196015@qq.com>
Date: Sun, 23 Aug 2026 17:25:41 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20MOD=5FGUIDE=20=E5=90=8C=E6=AD=A5=200.1.?=
 =?UTF-8?q?27?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 版本头 0.1.26→0.1.27；数据口五→六（新增 §5.5 世界数值 worldNum 白名单覆写）
- 安全红线补第 6 条（worldNum 只动白名单键）
- 依赖语义补充（注册库内自动先装）；§9 分发补「游戏内导出 MOD 集」
- 范式一句话更新（六口入炉）
---
 docs/MOD_GUIDE.md | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/docs/MOD_GUIDE.md b/docs/MOD_GUIDE.md
index 34947d4..0d4d27d 100644
--- a/docs/MOD_GUIDE.md
+++ b/docs/MOD_GUIDE.md
@@ -1,6 +1,6 @@
 # MOD 规范与范式标准 · Chronicle of the Immortal Clan
 
-> 版本 **0.1.26·《墨规清辉》** · MOD_SCHEMA_VERSION = 1
+> 版本 **0.1.27·《活水长流》** · MOD_SCHEMA_VERSION = 1
 > 每个 MOD 是一个**外部内容包**（纯 JSON，零脚本）；安装后成为插件一等子类，
 > 享有插件的全部设施：持久化（随档）、启用/停用、依赖/冲突检查、卸载自动回滚。
 
@@ -35,7 +35,8 @@
     "calamities": [ { "name": "剑灾", "family": { "lingcao": 0.7 }, "effect": { "beastcore": 0.2 } } ],
     "pills": [ /* PillRecipe 追加 */ ],
     "forges": [ /* ForgeRecipe 追加 */ ]
-  }
+  },
+  "worldNum": { "calamityChance": 0.12, "npcTradeRate": 0.006 }  // 0.1.27：世界数值白名单覆写（见 §5.5）
 }
 ```
 
@@ -93,6 +94,24 @@ EventDef 全字段**纯数据**（与内置事件同构）：
 - `effect`：**世界市场**池冲击乘量（-0.3 意为减少 30%）
 - 灾签与世界循环（减产/市价/快讯/体感）全链路自动生效——这是本作灾年机制的扩展口
 
+## 5.5 世界数值（worldNum，0.1.27 起）
+
+```jsonc
+"worldNum": {
+  "calamityChance": 0.12,      // 灾年概率（默认 0.18）
+  "worldSupplyRate": 0.015,    // 世界月供给（默认 0.02）
+  "worldDemandRate": 0.012,    // 世界月需求（默认 0.015）
+  "npcTradeRate": 0.006,       // NPC 月贸易量（默认 0.008）
+  "greatNewbornChance": 0.08,  // 新贵补位率（默认 0.06）
+  "secretRecover": 1,          // 秘境灵气月恢复（默认 2）
+  "tradeFloorPct": 0.3         // 断供拒单线（默认 0.35；勿与 poolFloorPct 分离）
+}
+```
+
+- **白名单**：仅 `WORLDSIM` 表内数值键可覆写（未知键忽略）；覆写可随卸载自动复位；
+- **纪律**：数值建议贴近现状量级；`marketRebalance`（弱锚定 0.025）与 `poolFloorPct` 属世界平衡核心，默认不建议 MOD 修改；
+- 接口：`overrideWorldNum(key, value)` / `resetWorldNum()`（引擎侧），MOD 作者在文档注解即可。
+
 ## 6. 配方（pills / forges）
 
 ```jsonc
@@ -111,6 +130,7 @@ EventDef 全字段**纯数据**（与内置事件同构）：
 3. **不改核心时序**：不重排 phase、不覆盖 advanceMonth；扩展走事件池/模板/灾因/配方/词库五口。
 4. **语义克制**：数值建议贴近现状量级（power 60~400、weight 0~100、成本仅低于内置顶级丹）。
 5. **命名唯一**：id/event id/模板 id/灾因名/配方 output 五个命名空间全部唯一。
+6. **worldNum 只动白名单**：覆写仅限 §5.5 列出的键（引擎 `overrideWorldNum` 校验），不碰 rebalance/池底等平衡核心。
 
 ## 8. 已验证的安装流程（行为承诺）
 
@@ -122,8 +142,9 @@ EventDef 全字段**纯数据**（与内置事件同构）：
 ## 9. 打包与分发
 
 - 单文件 `.cotymod`（= JSON）直接分发；放入 `userData/mods/` 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。
+- **游戏内导出**（0.1.27）：「MOD 层 → 导出当前 MOD 集」会把当前启用的全部 MOD 合并为 `mod-bundle-export.cotymod`（含各包明细）——分享/备份走同一载入通道。
 - 注意：**MOD 只影响新开档**的世界生成；已开档不受影响（世界种已落档）。
 
 ---
 
-**一句话范式**：MOD = "给世界的材料包"——五口（事件/模板/词库/灾因/配方）入炉，生成与演化由引擎统一烹调。
+**一句话范式**：MOD = "给世界的材料包"——六口（事件/模板/词库/灾因/配方/世界数值）入炉，生成与演化由引擎统一烹调。