diff --git a/AGENTS.md b/AGENTS.md index 00311302..21170139 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -269,8 +269,8 @@ bash scripts/validate-csharp-naming.sh - Treat source code, `*.csproj`, tests, generated snapshots, and packaging metadata as the primary evidence for documentation updates. -- Treat `CoreGrid` as a secondary evidence source for real project adoption patterns, directory layouts, and end-to-end - usage examples. +- Treat verified reference implementations under `ai-libs/` as a secondary evidence source for real project adoption + patterns, directory layouts, and end-to-end usage examples. - Treat existing `README.md` files and `docs/zh-CN/` pages as editable outputs, not authoritative truth. - If existing documentation conflicts with code or tests, update the documentation to match the implementation instead of preserving outdated wording. diff --git a/GFramework.Game.Abstractions/README.md b/GFramework.Game.Abstractions/README.md index eb2031c7..91fa5f32 100644 --- a/GFramework.Game.Abstractions/README.md +++ b/GFramework.Game.Abstractions/README.md @@ -25,7 +25,8 @@ - `FileStorage`、`ScopedStorage`、`JsonSerializer`、`SettingsModel`、`SaveRepository`、`SceneRouterBase`、`UiRouterBase`、`YamlConfigLoader` 等都在实现这里的契约。 - 引擎适配包或项目代码 - `IUiFactory`、`ISceneFactory`、`IUiRoot`、`ISceneRoot`、资源注册表等通常由引擎适配层或游戏项目自己实现。 - - CoreGrid 的真实结构也是这样:页面/场景 factory、root、registry 在项目层,运行时基类和契约来自 `GFramework.Game` 与本包。 + - 仓库内 `ai-libs/` 下的只读参考实现通常也是这样组织:页面 / 场景 factory、root、registry 在项目层, + 运行时基类和契约来自 `GFramework.Game` 与本包。 ## 子系统地图 @@ -195,9 +196,9 @@ public sealed class ContinueGameCommandHandler 也就是说,本包回答的是“项目各层如何约定”,`GFramework.Game` 回答的是“这些约定默认怎么跑起来”。 -## CoreGrid 里的真实用法线索 +## `ai-libs/` 里的参考接入线索 -CoreGrid 对本包的使用方式,能比较清楚地说明它的职责边界: +`ai-libs/` 下的只读参考实现对本包的使用方式,能比较清楚地说明它的职责边界: - 公共脚本广泛引用: - `IUiRouter` @@ -213,7 +214,7 @@ CoreGrid 对本包的使用方式,能比较清楚地说明它的职责边界 - 真正的实现和装配则放在: - `GFramework.Game` - `GFramework.Godot.*` - - CoreGrid 自己的模块、factory、root、registry + - 项目自己的模块、factory、root、registry 这正是本包的设计目标:让业务层依赖稳定契约,而不是依赖具体运行时细节。 diff --git a/GFramework.Game/README.md b/GFramework.Game/README.md index 2b0cf825..60336e82 100644 --- a/GFramework.Game/README.md +++ b/GFramework.Game/README.md @@ -31,7 +31,8 @@ - 引擎适配包或项目内适配层 - 本包提供的是“引擎无关”的核心逻辑和基类。 - 真正和 Godot、Unity、MonoGame 等引擎对象打交道的工厂、根节点、资源注册表,通常在相邻引擎包或游戏项目内实现。 - - CoreGrid 的真实接法就是这样:配置文件 IO 由 `GFramework.Godot.Config` 适配,UI/Scene factory 与 root 由项目自己提供。 + - 仓库内 `ai-libs/` 下的只读参考实现通常也是这样接入:配置文件 IO 由 `GFramework.Godot.Config` 适配, + UI / Scene factory 与 root 由项目自己提供。 ## 子系统地图 @@ -72,7 +73,7 @@ - `SaveConfiguration` - 槽位目录、文件名、前缀等约定 -CoreGrid 的真实用法: +`ai-libs/` 下已验证参考实现的常见接法: - 设置持久化使用 `UnifiedSettingsDataRepository` - 存档使用 `SaveRepository` @@ -95,7 +96,7 @@ CoreGrid 的真实用法: - `Setting/Events/*` - 设置初始化、应用、保存、重置相关事件 -CoreGrid 的真实用法: +`ai-libs/` 下已验证参考实现的常见接法: - 在模型模块中创建 `SettingsModel` - 注册多个 applicator @@ -148,7 +149,7 @@ CoreGrid 的真实用法: - `Scene/Handler/*`、`UI/Handler/*` - 默认转换处理器基类与日志处理器 -CoreGrid 的真实用法: +`ai-libs/` 下已验证参考实现的常见接法: - 项目自定义 `SceneRouter : SceneRouterBase` - 项目自定义 `UiRouter : UiRouterBase` @@ -253,7 +254,7 @@ await settingsSystem.ApplyAll(); await settingsSystem.SaveAll(); ``` -CoreGrid 目前就是按这个思路接入,只是底层存储换成了 Godot 适配实现。 +`ai-libs/` 下的只读参考实现目前也是按这个思路接入,只是底层存储换成了 Godot 适配实现。 ### 3. 接入静态 YAML 配置 @@ -311,18 +312,18 @@ public sealed class MyUiRouter : UiRouterBase 这类 router 适合作为你的项目层或引擎适配层代码,而不是直接修改本包。 -## CoreGrid 里的真实用法线索 +## `ai-libs/` 里的参考接入线索 -当前仓库内,CoreGrid 对本包的使用大致分成三层: +当前仓库内的只读参考实现,对本包的使用大致分成三层: - 配置 - - `CoreGridConfigHost` 使用生成表元数据与 YAML loader 完成配置注册 + - 项目级配置宿主类型使用生成表元数据与 YAML loader 完成配置注册 - 设置与存档 - - `UtilityModule` 注册序列化器、底层存储、`UnifiedSettingsDataRepository`、`SaveRepository` - - `ModelModule` 创建 `SettingsModel` 并注册 applicator + - 项目层 utility 模块注册序列化器、底层存储、`UnifiedSettingsDataRepository`、 + `SaveRepository` + - 项目层 model 模块创建 `SettingsModel` 并注册 applicator - 路由 - - `SceneRouter` 继承 `SceneRouterBase` - - `UiRouter` 继承 `UiRouterBase` + - 项目自定义 `SceneRouterBase` / `UiRouterBase` 的派生类型 这说明本包更适合做“游戏基础设施层”,而不是把所有引擎对象耦死在包内部。 diff --git a/ai-plan/public/documentation-governance-and-refresh/todos/documentation-governance-and-refresh-tracking.md b/ai-plan/public/documentation-governance-and-refresh/todos/documentation-governance-and-refresh-tracking.md index 0447eb82..c12904e4 100644 --- a/ai-plan/public/documentation-governance-and-refresh/todos/documentation-governance-and-refresh-tracking.md +++ b/ai-plan/public/documentation-governance-and-refresh/todos/documentation-governance-and-refresh-tracking.md @@ -34,7 +34,7 @@ - 旧专题页示例失真风险:`docs/zh-CN/core/*`、`game/*` 与 `source-generators/*` 中仍可能保留看似合理但与 真实实现不一致的示例 - - 缓解措施:继续按源码、测试、`*.csproj` 与 `CoreGrid` 真实接法核对,不把旧文档当事实来源 + - 缓解措施:继续按源码、测试、`*.csproj` 与 `ai-libs/` 下已验证参考实现核对,不把旧文档当事实来源 - 采用路径误导风险:根聚合包与模块边界若再次被写错,会继续误导消费者的包选择 - 缓解措施:保持“源码与包关系优先”的证据顺序,改动采用说明时同步核对包依赖与生成器 wiring - Active 入口回膨胀风险:后续若把栏目级重写过程直接追加到 active 文档,会再次拖慢恢复 diff --git a/ai-plan/public/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md b/ai-plan/public/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md index 6b9bb94e..f0164e42 100644 --- a/ai-plan/public/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md +++ b/ai-plan/public/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md @@ -52,3 +52,13 @@ 1. 审核 `docs/zh-CN/core/architecture.md`、`context.md`、`lifecycle.md`、`command.md`、`query.md`、`cqrs.md` 2. 记录每页的失真点、真实 API 名称与应保留的最小示例 3. 完成一轮专题页重写后再次执行 `cd docs && bun run build` + +### 补充:2026-04-21 内容引用迁移 + +- 按当前文档治理主题,继续清理活跃规范与面向读者的内容入口中的旧参考仓库命名 +- `AGENTS.md` 已把“secondary evidence source”从特定项目名收口为 `ai-libs/` 下的已验证只读参考实现 +- `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md` 与 + `docs/zh-CN/game/index.md` 已同步改为 `ai-libs/` 参考表述,并去掉特定参考项目名称与项目内类型名线索 +- `documentation-governance-and-refresh` active tracking 已同步把风险缓解中的参考来源更新为 + `ai-libs/` 下已验证参考实现 +- 下一次专题页重写时,继续沿用同一表述,不再把特定参考项目名写入新的活跃文档入口 diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index 7a0738dd..59a00443 100644 --- a/docs/zh-CN/game/index.md +++ b/docs/zh-CN/game/index.md @@ -100,9 +100,9 @@ IStorage storage = new FileStorage("GameData", serializer); ## 与真实接法的关系 -这个栏目以源码、`*.csproj`、模块 `README.md` 与 `CoreGrid` 中已验证的接法为准。 +这个栏目以源码、`*.csproj`、模块 `README.md` 与 `ai-libs/` 下已验证的参考接法为准。 -例如当前仓库与 `CoreGrid` 的共同事实包括: +例如当前文档应优先和以下已验证事实保持一致: - 配置系统采用 `YAML + JSON Schema + Source Generator` - 设置持久化通常通过 `UnifiedSettingsDataRepository`