docs(game): 补齐配置工具能力边界说明

- 更新 config system 与 config tool 的 reader-facing 边界说明

- 补充 additionalProperties:false、oneOf/anyOf rejection 与 raw YAML 回退路径

- 记录本批次 Tooling/Docs 收口验证与下一步

ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md

@@ -93,9 +93,12 @@
   - `dotnet build GFramework.sln -c Release`：通过（存在仓库既有 analyzer warning，无新增错误）
 - `2026-04-30` Tooling lane 收口验证：
   - `dotnet build GFramework.sln -c Release`：通过（0 Warnings, 0 Errors；本轮仅改 ai-plan 文件，确认没有伴随未验证的代码漂移）
+- `2026-04-30` Tooling / Docs reader-facing 收口：
+  - `git diff --check -- docs/zh-CN/game/config-tool.md docs/zh-CN/game/config-system.md tools/gframework-config-tool/README.md ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md`：通过
+  - 已补齐工具能力边界、`additionalProperties: false` / `oneOf` / `anyOf` 说明、工具与 Runtime 契约关系，以及复杂 shape 的 raw YAML 回退路径
 
 ## 下一步
 
 1. 主线继续回到 `YamlConfigSchemaValidator.cs`、`SchemaConfigGenerator.cs` 与 `configValidation.js` 的共享关键字盘点，默认跳过 `oneOf` / `anyOf`
-2. Tooling / Docs 若要并发推进，直接从 `ai-first-config-system-csharp-experience-next.md` 的并行 lane 开新 batch，不再扩写 active 入口
+2. Tooling / Docs 若要并发推进，优先补 reader-facing 示例或采用路径，不再重复扩写能力边界说明
 3. 保持 active tracking / trace 精简，只记录当前恢复点、最近验证和下一步恢复指针

ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md

@@ -164,3 +164,28 @@
 1. 若继续做主线代码批次，直接回到共享关键字盘点，不让 Tooling / Docs 成为阻塞条件
 2. 若另开 Tooling / Docs batch，先读取 `ai-first-config-system-csharp-experience-next.md` 的并行 lane，再把结果摘要写回 active tracking / trace
 3. 继续保持 active 入口精简，不在默认恢复文件中追加 UI 细节、治理台账或面向读者的文档草稿
+
+## 2026-04-30
+
+### 阶段：Tooling / Docs reader-facing 边界补齐（AI-FIRST-CONFIG-RP-003）
+
+- 已在 `config-tool.md`、`config-system.md` 和 `tools/gframework-config-tool/README.md` 明确 reader-facing 能力边界
+- 本轮重点不是新增能力，而是把当前分支已经落地的结论写清楚：
+  - `contains` / `minContains` / `maxContains`
+  - `dependentRequired`、`dependentSchemas`、`allOf`
+  - object-focused `if` / `then` / `else`
+  - `additionalProperties: false`
+  - `oneOf` / `anyOf` rejection
+- 同时补充了两个采用原则：
+  - VS Code 工具是辅助层，不定义 Runtime 契约
+  - 复杂 shape 或超出共享子集的 schema，应回退到 raw YAML 与 schema 文件本体处理
+
+### 验证
+
+- 2026-04-30：`git diff --check -- docs/zh-CN/game/config-tool.md docs/zh-CN/game/config-system.md tools/gframework-config-tool/README.md ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md`
+  - 结果：通过
+
+### 下一步
+
+1. Tooling / Docs 后续若继续推进，优先补真实采用示例，而不是重复扩写边界清单
+2. 主线代码批次继续以 Runtime / Generator / Tooling 三端共享关键字收口为中心

docs/zh-CN/game/config-system.md

@@ -17,10 +17,20 @@ description: 说明 GFramework.Game 配置系统的定位、目录约定、生
 - JSON Schema 作为结构描述
 - 一对象一文件的目录组织
 - 运行时只读查询
-- Runtime / Generator / Tooling 共享支持 `enum`、`const`、`not`、`minimum`、`maximum`、`exclusiveMinimum`、`exclusiveMaximum`、`multipleOf`、`minLength`、`maxLength`、`pattern`、`format`（当前稳定子集：`date`、`date-time`、`duration`、`email`、`time`、`uri`、`uuid`）、`minItems`、`maxItems`、`uniqueItems`、`contains`、`minContains`、`maxContains`、`minProperties`、`maxProperties`、`dependentRequired`、`dependentSchemas`、`allOf`、`if` / `then` / `else`
+- Runtime / Generator / Tooling 共享支持 `enum`、`const`、`not`、`minimum`、`maximum`、`exclusiveMinimum`、`exclusiveMaximum`、`multipleOf`、`minLength`、`maxLength`、`pattern`、`format`（当前稳定子集：`date`、`date-time`、`duration`、`email`、`time`、`uri`、`uuid`）、`minItems`、`maxItems`、`uniqueItems`、`contains`、`minContains`、`maxContains`、`minProperties`、`maxProperties`、`dependentRequired`、`dependentSchemas`、`allOf`、object-focused `if` / `then` / `else`，以及闭合对象边界 `additionalProperties: false`
 - Source Generator 生成配置类型、表包装、单表注册/访问辅助，以及项目级聚合注册目录
 - VS Code 插件提供配置浏览、raw 编辑、schema 打开、递归轻量校验和嵌套对象表单入口
 
+## 编辑器能力与 Runtime 契约
+
+`GFramework Config Tool` 是这套配置系统的辅助层，不单独定义 Runtime 契约。
+
+- 哪些 schema 能被正式采用，以 `GFramework.Game` Runtime 与 Source Generator 的共享支持边界为准
+- VS Code 插件负责把这些已落地的边界提前暴露成浏览、表单、校验和批量编辑体验
+- 工具层的可视化入口比 Runtime 契约更保守时，应该回到 raw YAML 和 schema 本体继续编辑，而不是把“当前没做成表单”误解为“运行时允许自由扩展”
+
+因此，判断某个关键字是否可用时，应该先看这里定义的共享契约，再把工具当作帮助你按这份契约工作的编辑器入口。
+
 对应工具说明见：[VS Code 配置工具](./config-tool.md)
 
 ## 推荐目录结构
@@ -802,8 +812,15 @@ 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 语义把每个条目叠加到当前对象上，不做属性合并，也不改变生成类型形状
 - `if` / `then` / `else`：供运行时校验、VS Code 校验、对象 section 表单 hint 和生成代码 XML 文档复用；当前只接受 object 节点上的 object-typed inline schema，`if` 必填且必须至少配合 `then` 或 `else` 之一使用，分支只能约束父对象已声明的字段，不做属性合并，也不改变生成类型形状；条件匹配本身沿用 `dependentSchemas` / `allOf` 的 focused matcher 语义，允许对象保留未在条件块中声明的额外同级字段
+- `additionalProperties`：当前共享支持边界只接受 `additionalProperties: false`；它用于声明对象是闭合的，运行时、生成器和工具都会据此拒绝未声明字段。其他 `additionalProperties` 形态当前不属于共享支持子集，会在解析或生成阶段直接被拒绝
 - `oneOf` / `anyOf`：当前不属于共享支持子集；Runtime / Generator / Tooling 会在解析或生成阶段直接拒绝，避免静默接受会改变生成类型形状的组合关键字
 
+如果你的 schema 需要超出这些边界的复杂 shape，推荐采用下面的回退顺序：
+
+1. 先在 raw YAML 与 schema 文件中直接编辑，而不是强行依赖表单入口
+2. 再核对该 shape 是否仍符合这里列出的共享支持子集
+3. 如果它依赖 `oneOf` / `anyOf`、非 `false` 的 `additionalProperties`、会向父对象注入新字段的 `allOf` / `dependentSchemas` / `if` 分支，或者更异构的深层数组结构，就应当把它视为当前版本之外的设计，而不是工具层遗漏的“隐藏能力”
+
 `allOf` 的最小可工作示例如下。关键点是：字段形状先在父对象 `properties` 中声明，再用 `allOf` 叠加 `required` 或更细的字段约束；`allOf` 条目不会把新字段并回父对象。
 
 ```json

docs/zh-CN/game/config-tool.md

@@ -83,6 +83,7 @@ Explorer + 表单预览。
 - 对空配置文件提供基于 schema 的示例 YAML 初始化入口
 - 对同一配置域内的多份 YAML 文件执行批量字段更新
 - 在表单入口中显示 `title / description / default / const / enum / x-gframework-ref-table（UI 中显示为 ref-table） / multipleOf / pattern / format / uniqueItems / contains / minContains / maxContains / minProperties / maxProperties / dependentRequired / dependentSchemas / allOf / if / then / else` 元数据；批量编辑入口当前只暴露顶层可批量改写字段所需的基础信息
+- 对 `additionalProperties: false` 提供闭合对象边界校验，并在遇到 `oneOf` / `anyOf` 或其他当前未收口的组合形状时明确提示该 schema 不属于当前工具支持子集
 
 当前表单入口适合编辑嵌套对象中的标量字段、标量数组，以及对象数组中的对象项。
 
@@ -98,6 +99,16 @@ Explorer + 表单预览。
 
 当前批量编辑入口仍刻意限制在“同域文件统一改动顶层标量字段和顶层标量数组”，避免复杂结构批量写回时破坏人工维护的 YAML 排版。
 
+### 工具边界与 Runtime 契约
+
+这个扩展是编辑器侧的辅助层，不定义 `GFramework.Game` 的 Runtime 契约。
+
+- Runtime / Source Generator 是否接受某份 schema，决定了它是否属于当前配置系统的正式支持范围
+- 工具里的表单、hint、校验和批量编辑，只是把这套已落地契约搬到 VS Code 中帮助你更快发现问题
+- 如果工具界面暂时没有把某个 shape 做成可视化编辑入口，不代表 Runtime 会自动接受更宽松的 schema；同样，如果 Runtime / Generator 已明确拒绝某类关键字，工具也不会把它包装成可继续编辑的“可用能力”
+
+日常采用时，建议把它理解为“优先用工具加速已支持子集的维护；遇到边界时立刻回到 schema + raw YAML 本体确认”。
+
 ## 推荐工作流
 
 ### 1. 浏览配置与 schema
@@ -124,6 +135,9 @@ Explorer + 表单预览。
 - 顶层标量数组
 - 嵌套对象字段
 - 对象数组
+- object-focused `if` / `then` / `else`、`dependentRequired`、`dependentSchemas`、`allOf`
+- `contains` / `minContains` / `maxContains`
+- `additionalProperties: false`
 
 如果你进入更深层对象数组嵌套，当前更稳妥的做法通常是：
 
@@ -131,6 +145,13 @@ Explorer + 表单预览。
 2. 先看表单预览确认字段结构
 3. 再回到 raw YAML 完成最终编辑
 
+以下 shape 目前也建议直接回退到 raw YAML，并同时检查 schema 是否仍在当前共享支持子集内：
+
+- 需要表达 `oneOf` / `anyOf` 这类会改变生成类型形状的组合关键字
+- 需要 `additionalProperties` 的其他形态，而不是当前明确支持的 `additionalProperties: false`
+- 需要在 `allOf`、`dependentSchemas`、`if` / `then` / `else` 中引入父对象未声明的新字段
+- 需要比当前对象数组编辑器更深、更异构的数组结构
+
 ## 工作区设置
 
 当前公开设置只有两个：
@@ -155,6 +176,7 @@ Explorer + 表单预览。
 - 校验聚焦仓库当前支持的 schema 子集
 - 表单预览支持对象数组，但更深的嵌套对象数组仍可能需要回退到 raw YAML
 - 批量编辑当前聚焦顶层标量和顶层标量数组字段
+- 共享约束里只支持闭合对象边界 `additionalProperties: false`；`oneOf` / `anyOf` 等改变生成形状的组合关键字会被明确拒绝
 
 因此，最稳妥的理解方式是：
 

tools/gframework-config-tool/README.md

@@ -78,6 +78,17 @@ The extension currently validates the repository's current schema subset:
 - array constraints such as `minItems`, `maxItems`, `contains`, `minContains`, `maxContains`, and `uniqueItems`
 - object constraints such as `minProperties`, `maxProperties`, `dependentRequired`, `dependentSchemas`, `allOf`, and
   object-focused `if` / `then` / `else`
+- closed-object validation through `additionalProperties: false`
+- explicit rejection for unsupported combinators such as `oneOf` and `anyOf`, instead of silently ignoring them
+
+## Contract Boundary
+
+This extension is an editor-side helper. It does not define the runtime contract for `GFramework.Game`.
+
+- The runtime and source generator remain the source of truth for which schema shapes are formally supported
+- The VS Code experience mirrors that shared subset so unsupported shapes fail early during browsing or validation
+- If a shape is too complex for the lightweight editors, fall back to raw YAML and the schema file first; do not assume
+  the runtime accepts a broader contract just because the editor has no custom form for it
 
 ## Workspace Settings
 
@@ -98,6 +109,13 @@ The extension currently validates the repository's current schema subset:
 5. Open the lightweight form preview or domain batch editing actions, then fall back to raw YAML for deeper nested edits
    when needed.
 
+Use raw YAML directly when you need:
+
+- deeper or more heterogeneous array shapes
+- object rules centered on `allOf`, `dependentSchemas`, or object-focused `if` / `then` / `else`
+- `contains` / `minContains` / `maxContains` verification on structures that are easier to reason about in source form
+- schema designs outside the current shared subset, including `oneOf`, `anyOf`, or non-`false` `additionalProperties`
+
 ## Documentation
 
 - Chinese adoption guide: [Game 配置工具](../../docs/zh-CN/game/config-tool.md)
@@ -110,6 +128,8 @@ The extension currently validates the repository's current schema subset:
 - Form preview supports nested objects and object-array editing, but deeper nested object arrays inside array items still
   fall back to raw YAML
 - Batch editing remains limited to top-level scalar fields and top-level scalar arrays
+- Closed-object support is limited to `additionalProperties: false`, and unsupported combinators such as `oneOf` /
+  `anyOf` are rejected on purpose
 
 ## Local Testing