From 56a96b50fd5cd9b6c33751d2c8cab192fe68c50a Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 30 Apr 2026 11:57:53 +0800 Subject: [PATCH] =?UTF-8?q?docs(game):=20=E5=90=8C=E6=AD=A5=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E5=85=A5=E5=8F=A3=E9=87=87=E7=94=A8=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 Game 入口页的静态 YAML 配置接入提示，明确 Runtime 与 Source Generator 的共享契约优先级 - 补充安装入口对 additionalProperties: false 与 oneOf / anyOf 拒绝边界的 reader-facing 提示 - 优化入口页采用建议，说明复杂 shape 应回退到 raw YAML 与 schema 设计本体 --- docs/zh-CN/game/index.md | 9 ++++++++- docs/zh-CN/getting-started/installation.md | 2 ++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index a66304a6..c534fd80 100644 --- a/docs/zh-CN/game/index.md +++ b/docs/zh-CN/game/index.md @@ -83,6 +83,13 @@ IStorage storage = new FileStorage("GameData", serializer); - `GFramework.Game.SourceGenerators` - `schemas/**/*.schema.json` + `config/**/*.yaml` +这条工作流的正式契约，以 `GFramework.Game` Runtime 和 `GFramework.Game.SourceGenerators` 当前共享支持的 schema +子集为准。`VS Code` 配置工具主要负责编辑期提示和表单辅助，不单独扩展运行时可接受的 schema 形状。 + +开始接入时，建议先把 schema 约束控制在共享子集内，并尽早确认像 `additionalProperties: false` 这类已收口的对象边界，以及 +`oneOf` / `anyOf` 当前会被直接拒绝，而不是在工具里看起来“可以先写”。如果你的配置模型需要更深层的嵌套数组、联合分支或其他超出共享子集的复杂 +shape，优先回到 raw YAML 和 schema 设计本体处理，再决定是否拆分结构或调整约束方式。 + 完整约定见： - [配置系统](./config-system.md) @@ -120,7 +127,7 @@ IStorage storage = new FileStorage("GameData", serializer); - 运行时入口主要来自 `GFramework.Game` - 只依赖接口或拆分业务层时，补充 `GFramework.Game.Abstractions` - 需要静态内容配置类型和表包装生成时，再追加 `GFramework.Game.SourceGenerators` -- 需要编辑器侧内容维护工作流时，再看 [VS Code 配置工具](./config-tool.md) +- 需要编辑器侧内容维护工作流时，再看 [VS Code 配置工具](./config-tool.md)，并把它视为共享契约之上的辅助层 ## 对应模块入口 diff --git a/docs/zh-CN/getting-started/installation.md b/docs/zh-CN/getting-started/installation.md index 7d33eb7f..83e4bd03 100644 --- a/docs/zh-CN/getting-started/installation.md +++ b/docs/zh-CN/getting-started/installation.md @@ -46,6 +46,8 @@ GFramework 采用模块化设计，不同包提供不同的功能： - Arch ECS：直接安装 `GeWuYou.GFramework.Ecs.Arch`；如果只想共享宿主循环或接口边界，可改为 `GeWuYou.GFramework.Ecs.Arch.Abstractions` 如果你准备采用 AI-First 配置工作流，可以继续阅读 [游戏内容配置系统](../game/config-system.md) 与 [VS Code 配置工具](../game/config-tool.md)。 +接入时建议先按 Runtime + Source Generator 的共享 schema 子集设计配置模型，再把 `VS Code` 工具当作编辑辅助层来使用，而不是反过来以工具界面可编辑的 shape 作为正式契约。 +尤其需要尽早知道两个当前边界：对象闭合只收口到 `additionalProperties: false`，而 `oneOf` / `anyOf` 会被直接拒绝。若配置模型超出这组共享边界，优先回到 raw YAML 与 schema 本体调整结构，而不是把差异理解成工具遗漏能力。 ## 安装方式