From 66e1f06f2f3a9ff8476dae743dc9d31ba11d4a32 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Fri, 17 Apr 2026 15:01:17 +0800
Subject: [PATCH] =?UTF-8?q?docs(config):=20=E6=B7=BB=E5=8A=A0=E6=B8=B8?=
 =?UTF-8?q?=E6=88=8F=E5=86=85=E5=AE=B9=E9=85=8D=E7=BD=AE=E7=B3=BB=E7=BB=9F?=
 =?UTF-8?q?=E8=AF=A6=E7=BB=86=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 YAML 配置源文件支持说明
- 添加 JSON Schema 结构描述功能介绍
- 提供一对象一文件目录组织方式
- 说明运行时只读查询机制
- 详细介绍 Source Generator 生成配置类型功能
- 添加 VS Code 插件配置浏览功能说明
- 提供推荐目录结构和 Schema 示例
- 说明 Godot 文本配置桥接方式
- 添加运行时读取模板和热重载模板
- 说明跨表引用和校验行为
- 提供开发期热重载功能说明
- 添加生成器接入约定说明
- 详细介绍 VS Code 工具功能特性
---
 docs/zh-CN/game/config-system.md | 40 ++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/zh-CN/game/config-system.md b/docs/zh-CN/game/config-system.md
index 057c3fdd..1879854c 100644
--- a/docs/zh-CN/game/config-system.md
+++ b/docs/zh-CN/game/config-system.md
@@ -795,6 +795,46 @@ if (MonsterConfigBindings.References.TryGetByDisplayPath("dropItems", out var re
 - `dependentSchemas`：供运行时校验、VS Code 校验、对象 section 表单 hint 和生成代码 XML 文档复用；当前只接受“已声明 sibling 字段触发 object 子 schema”的形状，不改变生成类型形状，并按 focused constraint block 语义允许条件子 schema 未声明的额外同级字段继续存在
 - `allOf`：供运行时校验、VS Code 校验、对象 section 表单 hint 和生成代码 XML 文档复用；当前只接受 object 节点上的 object-typed inline schema 数组，并按 focused constraint block 语义把每个条目叠加到当前对象上，不做属性合并，也不改变生成类型形状
 
+`allOf` 的最小可工作示例如下。关键点是：字段形状先在父对象 `properties` 中声明，再用 `allOf` 叠加 `required` 或更细的字段约束；`allOf` 条目不会把新字段并回父对象。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "reward": {
+      "type": "object",
+      "properties": {
+        "itemId": { "type": "string" },
+        "itemCount": { "type": "integer" }
+      },
+      "allOf": [
+        {
+          "type": "object",
+          "required": ["itemCount"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "itemCount": {
+              "type": "integer",
+              "minimum": 2
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+```yaml
+reward:
+  itemId: potion
+  itemCount: 3
+```
+
+兼容性说明：如果你以前按标准 JSON Schema `allOf` 的直觉，把新字段只写进 `allOf` 条目的 `properties` 或 `required`，当前实现不会做属性合并，这类 schema 现在会在加载 / 生成 / 工具解析阶段直接被拒绝。请先把字段提升到父对象的 `properties`，再在 `allOf` 里补充 required 或约束。
+
 这样可以避免错误配置被默认值或 `IgnoreUnmatchedProperties` 静默吞掉。
 
 加载失败时，`YamlConfigLoader` 会抛出 `ConfigLoadException`。你可以通过 `exception.Diagnostic` 读取稳定字段，而不必解析消息文本：