From 01f1e5fd72f357a1690ba5cb730455281ae2dd8d Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 30 Apr 2026 12:06:56 +0800 Subject: [PATCH] =?UTF-8?q?docs(game):=20=E5=90=8C=E6=AD=A5=E6=95=B0?= =?UTF-8?q?=E6=8D=AE=E4=B8=8E=E8=AE=BE=E7=BD=AE=E5=85=A5=E5=8F=A3=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 补充 data 与 setting 入口对 AI-First 配置系统共享 schema 子集的 reader-facing 提示 - 说明 DataRepository、UnifiedSettingsDataRepository 与 SettingsModel 负责持久化和应用而不放宽配置契约 - 更新复杂 schema shape 回到 config-system 与 raw YAML 处理的采用指引 --- docs/zh-CN/game/data.md | 9 +++++++++ docs/zh-CN/game/setting.md | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/docs/zh-CN/game/data.md b/docs/zh-CN/game/data.md index a184e1a9..843ea4e5 100644 --- a/docs/zh-CN/game/data.md +++ b/docs/zh-CN/game/data.md @@ -18,6 +18,14 @@ description: 以当前 GFramework.Game 源码与 PersistenceTests 为准，说 如果先把这三类入口分开理解，后续接入时会清晰很多。 +## 与 AI-First 配置系统的边界 + +如果你是从 AI-First 配置工作流一路读到这里，需要先把“配置契约”和“运行时持久化”分开理解： + +- 配置系统的 schema 支持边界，仍以 `GFramework.Game` Runtime 和 `GFramework.Game.SourceGenerators` 当前共享的 schema 子集为准 +- `DataRepository`、`UnifiedSettingsDataRepository` 和 `SaveRepository` 负责的是数据怎么落盘、怎么回读、怎么组织槽位，而不是放宽配置契约 +- 如果配置设计依赖 `oneOf`、`anyOf`、非 `false` 的 `additionalProperties`，或其他更复杂的 schema shape，应直接回到 [配置系统](./config-system.md) 与 raw YAML / schema 本体继续处理，而不是期待 repository 层自动接管这些边界 + ## 什么时候用哪个仓库 ### `DataRepository` @@ -195,6 +203,7 @@ var saveConfiguration = new SaveConfiguration - `UnifiedSettingsDataRepository` 不是通用万能仓库，它专门服务“多 section 聚合单文件”的场景 - `SaveRepository` 不负责业务层的 autosave 策略、云同步或存档选择 UI - `LoadAsync(...)` 返回新实例的行为适合默认启动路径；如果项目需要“缺档即报错”，应在业务层显式调用 `ExistsAsync(...)` +- 如果 AI-First 配置系统里的 schema 已经超出 Runtime / Generator 共享子集，repository 也不会替你放宽这些约束；这时应优先回到 [配置系统](./config-system.md) 与 raw YAML / schema 设计本身 ## 继续阅读 diff --git a/docs/zh-CN/game/setting.md b/docs/zh-CN/game/setting.md index 67fab33e..a1e4d6cf 100644 --- a/docs/zh-CN/game/setting.md +++ b/docs/zh-CN/game/setting.md @@ -18,6 +18,14 @@ description: 以当前 SettingsModel、SettingsSystem 与相关测试为准， 而不是只靠若干 `Get() / Register(...)` 辅助方法就能自动完成一切的模型。 +## 与 AI-First 配置系统的边界 + +如果你关注的是“配置内容最后怎么变成运行时设置”，这里也需要先分清职责： + +- 配置 schema 的正式支持边界，仍以 `GFramework.Game` Runtime 和 `GFramework.Game.SourceGenerators` 当前共享的 schema 子集为准 +- `UnifiedSettingsDataRepository`、`SettingsModel` 和 `SettingsSystem` 负责设置数据的加载、迁移、保存与应用，不负责放宽 `oneOf`、`anyOf`、非 `false` 的 `additionalProperties` 等配置边界 +- 一旦配置设计开始依赖更复杂的 schema shape，应直接回到 [配置系统](./config-system.md) 与 raw YAML / schema 本体处理，再决定设置层怎么消费这些结果 + ## 当前公开入口 ### `ISettingsData` @@ -196,6 +204,7 @@ await settingsModel.SaveAllAsync(); - `SettingsModel` 负责数据生命周期，`SettingsSystem` 负责系统级调用入口；两者不要混成一个巨型服务 - applicator 决定“怎么把数据应用到宿主”，repository 决定“怎么保存数据”，两层职责不要互相侵入 - 设置迁移和存档迁移是两条不同管线；后者看 [数据与存档系统](./data.md) 里的 `SaveRepository` +- 如果某个配置 shape 已经超出 Runtime / Generator 共享支持子集，settings repository 和 `SettingsModel` 也不会替代配置系统去放宽它；应回到 [配置系统](./config-system.md) 与 raw YAML / schema 设计处理 ## 继续阅读