docs(config): 添加游戏内容配置系统完整文档#209
Conversation
- 新增面向静态游戏内容的 AI-First 配表方案介绍 - 详细说明 YAML 作为配置源文件和 JSON Schema 结构描述功能 - 提供推荐目录结构和 Schema 示例配置 - 添加 VS Code 插件工具支持说明 - 包含 Godot 文本配置桥接使用指南 - 提供运行时读取和热重载模板示例 - 说明生成器接入约定和运行时校验行为 - 添加开发期热重载和工具支持详细说明 - 创建 Godot 测试项目配置文件 - 实现 GodotYamlConfigLoader 配置加载适配层
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthrough新增 Godot 专用 YAML 配置加载器、选项与表源类型，加入 Godot 路径环境抽象；在导出模式下将已注册 YAML/schema 同步到 Changes
Sequence DiagramsequenceDiagram
actor Caller
participant Loader as GodotYamlConfigLoader
participant Env as GodotYamlConfigEnvironment
participant FS as Filesystem/Cache
participant YamlLoader as YamlConfigLoader
participant Registry as IConfigRegistry
Caller->>Loader: LoadAsync(registry, cancellation)
Loader->>Env: Globalize & 检查 SourceRootPath 可访问性
Env-->>Loader: 返回(是否可直接访问, 全局路径?)
alt 不可直接访问（导出/需缓存）
Loader->>FS: 枚举 TableSource 目录与 schema 文件
FS-->>Loader: 目录条目与文件内容
Loader->>FS: 重置/创建 runtime cache 并写入已注册 YAML/schema
FS-->>Loader: 写入完成
Loader->>YamlLoader: 指向 runtime cache 的 LoaderRootPath 并 调用 LoadAsync
else 可直接访问（编辑器）
Loader->>YamlLoader: 使用全局化的 res:// 路径 直接 LoadAsync
end
YamlLoader->>Registry: 解析并注册配置
Registry-->>YamlLoader: 注册完成
YamlLoader-->>Loader: 返回加载结果
Loader-->>Caller: 完成
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
审阅者指南为基于 YAML 的游戏配置系统补充了完整文档，并新增一个具体的 Godot 集成层：包括带 res:// / user:// 处理的 Godot 专用加载器、相关选项和表源模型类型，以及验证编辑器与导出行为、热重载约束的测试。 编辑器模式 vs 导出模式下 GodotYamlConfigLoader.LoadAsync 的时序图sequenceDiagram
actor GameCode
participant GodotYamlConfigLoader as GodotYamlConfigLoader
participant GodotYamlConfigEnvironment as Environment
participant YamlConfigLoader as YamlConfigLoader
GameCode->>GodotYamlConfigLoader: new GodotYamlConfigLoader(options)
activate GodotYamlConfigLoader
GodotYamlConfigLoader->>GodotYamlConfigLoader: ResolveLoaderRootPath()
alt SourceRootPath is Godot path
GodotYamlConfigLoader->>Environment: IsEditor()
alt Running_in_editor
GodotYamlConfigLoader->>Environment: GlobalizePath(SourceRootPath)
GodotYamlConfigLoader-->>GodotYamlConfigLoader: LoaderRootPath = globalized_res
else Exported_build
GodotYamlConfigLoader->>Environment: GlobalizePath(RuntimeCacheRootPath)
GodotYamlConfigLoader-->>GodotYamlConfigLoader: LoaderRootPath = globalized_user_cache
end
else SourceRootPath is normal or user path
GodotYamlConfigLoader-->>GodotYamlConfigLoader: LoaderRootPath = full_path(SourceRootPath)
end
GodotYamlConfigLoader->>GodotYamlConfigLoader: _loader = new YamlConfigLoader(LoaderRootPath)
GodotYamlConfigLoader->>GodotYamlConfigLoader: options.ConfigureLoader(_loader)
deactivate GodotYamlConfigLoader
GameCode->>GodotYamlConfigLoader: LoadAsync(registry)
activate GodotYamlConfigLoader
alt CanEnableHotReload == false
GodotYamlConfigLoader->>GodotYamlConfigLoader: SynchronizeRuntimeCache()
loop For each config path group
GodotYamlConfigLoader->>Environment: EnumerateDirectory(res_config_dir)
alt Directory_not_found
GodotYamlConfigLoader-->>GameCode: throw ConfigLoadException
else Directory_found
loop For each yaml file
GodotYamlConfigLoader->>Environment: FileExists(filePath)
alt Missing_or_read_error
GodotYamlConfigLoader-->>GameCode: throw ConfigLoadException
else OK
GodotYamlConfigLoader->>Environment: ReadAllBytes(filePath)
GodotYamlConfigLoader->>FileSystem: WriteAllBytes(cacheFilePath)
end
end
end
end
note over GodotYamlConfigLoader,YamlConfigLoader: LoaderRootPath points to user:// runtime cache
else CanEnableHotReload == true
note over GodotYamlConfigLoader,YamlConfigLoader: LoaderRootPath points to project directory
end
GodotYamlConfigLoader->>YamlConfigLoader: LoadAsync(registry)
YamlConfigLoader-->>GodotYamlConfigLoader: Completed
GodotYamlConfigLoader-->>GameCode: Completed
deactivate GodotYamlConfigLoader
GameCode->>GodotYamlConfigLoader: EnableHotReload(registry)
alt CanEnableHotReload == false
GodotYamlConfigLoader-->>GameCode: throw InvalidOperationException
else CanEnableHotReload == true
GodotYamlConfigLoader->>YamlConfigLoader: EnableHotReload(registry, options)
YamlConfigLoader-->>GodotYamlConfigLoader: IUnRegister
GodotYamlConfigLoader-->>GameCode: IUnRegister
end
新 Godot YAML 配置加载器集成的类图classDiagram
direction LR
class IConfigLoader {
<<interface>>
+LoadAsync(registry IConfigRegistry, cancellationToken CancellationToken) Task
}
class IConfigRegistry {
<<interface>>
}
class IUnRegister {
<<interface>>
}
class YamlConfigLoader {
+YamlConfigLoader(rootPath string)
+LoadAsync(registry IConfigRegistry, cancellationToken CancellationToken) Task
+EnableHotReload(registry IConfigRegistry, options YamlConfigHotReloadOptions) IUnRegister
}
class YamlConfigHotReloadOptions
class ConfigLoadException
class ConfigLoadDiagnostic
class ConfigLoadFailureKind
class GodotYamlConfigLoaderOptions {
+SourceRootPath string
+RuntimeCacheRootPath string
+TableSources IReadOnlyCollection~GodotYamlConfigTableSource~
+ConfigureLoader Action~YamlConfigLoader~
}
class GodotYamlConfigTableSource {
+GodotYamlConfigTableSource(tableName string, configRelativePath string, schemaRelativePath string)
+TableName string
+ConfigRelativePath string
+SchemaRelativePath string
}
class GodotYamlConfigLoader {
-_environment GodotYamlConfigEnvironment
-_loader YamlConfigLoader
-_options GodotYamlConfigLoaderOptions
+GodotYamlConfigLoader(options GodotYamlConfigLoaderOptions)
+GodotYamlConfigLoader(options GodotYamlConfigLoaderOptions, environment GodotYamlConfigEnvironment)
+SourceRootPath string
+RuntimeCacheRootPath string
+LoaderRootPath string
+Loader YamlConfigLoader
+CanEnableHotReload bool
+LoadAsync(registry IConfigRegistry, cancellationToken CancellationToken) Task
+EnableHotReload(registry IConfigRegistry, options YamlConfigHotReloadOptions) IUnRegister
-ResolveLoaderRootPath() string
-UsesSourceDirectoryDirectly(sourceRootPath string) bool
-SynchronizeRuntimeCache(cancellationToken CancellationToken) void
-CopyYamlFilesInDirectory(tableName string, sourceDirectoryPath string, targetDirectoryPath string, cancellationToken CancellationToken) void
-CopySingleFile(tableName string, sourceFilePath string, targetAbsolutePath string, missingFailureKind ConfigLoadFailureKind, readFailureKind ConfigLoadFailureKind, configDirectoryPath string, yamlPath string) void
-ResetDirectory(directoryPath string) void
-EnsureAbsolutePath(path string, optionName string) string
-DescribePath(path string) string
-CombinePath(rootPath string, relativePath string) string
-CombineAbsolutePath(rootPath string, relativePath string) string
-NormalizeRelativePath(relativePath string) string
-IsYamlFile(fileName string) bool
-CreateConfigLoadException(failureKind ConfigLoadFailureKind, tableName string, message string, configDirectoryPath string, yamlPath string, schemaPath string, innerException Exception) ConfigLoadException
}
class GodotYamlConfigEnvironment {
+GodotYamlConfigEnvironment(isEditor Func~bool~, globalizePath Func~string,string~, enumerateDirectory Func~string,IReadOnlyList~GodotYamlConfigDirectoryEntry~~, fileExists Func~string,bool~, readAllBytes Func~string,byte[]~)
+IsEditor Func~bool~
+GlobalizePath Func~string,string~
+EnumerateDirectory Func~string,IReadOnlyList~GodotYamlConfigDirectoryEntry~?~
+FileExists Func~string,bool~
+ReadAllBytes Func~string,byte[]~
+Default GodotYamlConfigEnvironment
-EnumerateDirectoryCore(path string) IReadOnlyList~GodotYamlConfigDirectoryEntry~?
-FileExistsCore(path string) bool
-ReadAllBytesCore(path string) byte[]
}
class GodotYamlConfigDirectoryEntry {
+Name string
+IsDirectory bool
}
GodotYamlConfigLoader ..|> IConfigLoader
GodotYamlConfigLoader o--> GodotYamlConfigLoaderOptions
GodotYamlConfigLoader o--> GodotYamlConfigEnvironment
GodotYamlConfigLoader o--> YamlConfigLoader
GodotYamlConfigLoaderOptions "1" o--> "*" GodotYamlConfigTableSource
GodotYamlConfigEnvironment --> GodotYamlConfigDirectoryEntry
YamlConfigLoader ..> IConfigLoader
YamlConfigLoader ..> YamlConfigHotReloadOptions
YamlConfigLoader ..> IConfigRegistry
GodotYamlConfigLoader ..> IConfigRegistry
GodotYamlConfigLoader ..> IUnRegister
GodotYamlConfigLoader ..> ConfigLoadException
GodotYamlConfigLoader ..> ConfigLoadDiagnostic
GodotYamlConfigLoader ..> ConfigLoadFailureKind
GodotYamlConfigLoader ..> GodotYamlConfigDirectoryEntry
文件级变更
技巧与命令与 Sourcery 交互
自定义你的使用体验进入你的 控制面板 以：
获取帮助Original review guide in EnglishReviewer's GuideAdds full documentation and a concrete Godot integration layer for the YAML-based game config system, including a Godot-specific loader with res:// / user:// handling, associated options and table-source model types, plus tests validating editor vs export behavior and hot-reload constraints. Sequence diagram for GodotYamlConfigLoader.LoadAsync in editor vs exportsequenceDiagram
actor GameCode
participant GodotYamlConfigLoader as GodotYamlConfigLoader
participant GodotYamlConfigEnvironment as Environment
participant YamlConfigLoader as YamlConfigLoader
GameCode->>GodotYamlConfigLoader: new GodotYamlConfigLoader(options)
activate GodotYamlConfigLoader
GodotYamlConfigLoader->>GodotYamlConfigLoader: ResolveLoaderRootPath()
alt SourceRootPath is Godot path
GodotYamlConfigLoader->>Environment: IsEditor()
alt Running_in_editor
GodotYamlConfigLoader->>Environment: GlobalizePath(SourceRootPath)
GodotYamlConfigLoader-->>GodotYamlConfigLoader: LoaderRootPath = globalized_res
else Exported_build
GodotYamlConfigLoader->>Environment: GlobalizePath(RuntimeCacheRootPath)
GodotYamlConfigLoader-->>GodotYamlConfigLoader: LoaderRootPath = globalized_user_cache
end
else SourceRootPath is normal or user path
GodotYamlConfigLoader-->>GodotYamlConfigLoader: LoaderRootPath = full_path(SourceRootPath)
end
GodotYamlConfigLoader->>GodotYamlConfigLoader: _loader = new YamlConfigLoader(LoaderRootPath)
GodotYamlConfigLoader->>GodotYamlConfigLoader: options.ConfigureLoader(_loader)
deactivate GodotYamlConfigLoader
GameCode->>GodotYamlConfigLoader: LoadAsync(registry)
activate GodotYamlConfigLoader
alt CanEnableHotReload == false
GodotYamlConfigLoader->>GodotYamlConfigLoader: SynchronizeRuntimeCache()
loop For each config path group
GodotYamlConfigLoader->>Environment: EnumerateDirectory(res_config_dir)
alt Directory_not_found
GodotYamlConfigLoader-->>GameCode: throw ConfigLoadException
else Directory_found
loop For each yaml file
GodotYamlConfigLoader->>Environment: FileExists(filePath)
alt Missing_or_read_error
GodotYamlConfigLoader-->>GameCode: throw ConfigLoadException
else OK
GodotYamlConfigLoader->>Environment: ReadAllBytes(filePath)
GodotYamlConfigLoader->>FileSystem: WriteAllBytes(cacheFilePath)
end
end
end
end
note over GodotYamlConfigLoader,YamlConfigLoader: LoaderRootPath points to user:// runtime cache
else CanEnableHotReload == true
note over GodotYamlConfigLoader,YamlConfigLoader: LoaderRootPath points to project directory
end
GodotYamlConfigLoader->>YamlConfigLoader: LoadAsync(registry)
YamlConfigLoader-->>GodotYamlConfigLoader: Completed
GodotYamlConfigLoader-->>GameCode: Completed
deactivate GodotYamlConfigLoader
GameCode->>GodotYamlConfigLoader: EnableHotReload(registry)
alt CanEnableHotReload == false
GodotYamlConfigLoader-->>GameCode: throw InvalidOperationException
else CanEnableHotReload == true
GodotYamlConfigLoader->>YamlConfigLoader: EnableHotReload(registry, options)
YamlConfigLoader-->>GodotYamlConfigLoader: IUnRegister
GodotYamlConfigLoader-->>GameCode: IUnRegister
end
Class diagram for new Godot YAML config loader integrationclassDiagram
direction LR
class IConfigLoader {
<<interface>>
+LoadAsync(registry IConfigRegistry, cancellationToken CancellationToken) Task
}
class IConfigRegistry {
<<interface>>
}
class IUnRegister {
<<interface>>
}
class YamlConfigLoader {
+YamlConfigLoader(rootPath string)
+LoadAsync(registry IConfigRegistry, cancellationToken CancellationToken) Task
+EnableHotReload(registry IConfigRegistry, options YamlConfigHotReloadOptions) IUnRegister
}
class YamlConfigHotReloadOptions
class ConfigLoadException
class ConfigLoadDiagnostic
class ConfigLoadFailureKind
class GodotYamlConfigLoaderOptions {
+SourceRootPath string
+RuntimeCacheRootPath string
+TableSources IReadOnlyCollection~GodotYamlConfigTableSource~
+ConfigureLoader Action~YamlConfigLoader~
}
class GodotYamlConfigTableSource {
+GodotYamlConfigTableSource(tableName string, configRelativePath string, schemaRelativePath string)
+TableName string
+ConfigRelativePath string
+SchemaRelativePath string
}
class GodotYamlConfigLoader {
-_environment GodotYamlConfigEnvironment
-_loader YamlConfigLoader
-_options GodotYamlConfigLoaderOptions
+GodotYamlConfigLoader(options GodotYamlConfigLoaderOptions)
+GodotYamlConfigLoader(options GodotYamlConfigLoaderOptions, environment GodotYamlConfigEnvironment)
+SourceRootPath string
+RuntimeCacheRootPath string
+LoaderRootPath string
+Loader YamlConfigLoader
+CanEnableHotReload bool
+LoadAsync(registry IConfigRegistry, cancellationToken CancellationToken) Task
+EnableHotReload(registry IConfigRegistry, options YamlConfigHotReloadOptions) IUnRegister
-ResolveLoaderRootPath() string
-UsesSourceDirectoryDirectly(sourceRootPath string) bool
-SynchronizeRuntimeCache(cancellationToken CancellationToken) void
-CopyYamlFilesInDirectory(tableName string, sourceDirectoryPath string, targetDirectoryPath string, cancellationToken CancellationToken) void
-CopySingleFile(tableName string, sourceFilePath string, targetAbsolutePath string, missingFailureKind ConfigLoadFailureKind, readFailureKind ConfigLoadFailureKind, configDirectoryPath string, yamlPath string) void
-ResetDirectory(directoryPath string) void
-EnsureAbsolutePath(path string, optionName string) string
-DescribePath(path string) string
-CombinePath(rootPath string, relativePath string) string
-CombineAbsolutePath(rootPath string, relativePath string) string
-NormalizeRelativePath(relativePath string) string
-IsYamlFile(fileName string) bool
-CreateConfigLoadException(failureKind ConfigLoadFailureKind, tableName string, message string, configDirectoryPath string, yamlPath string, schemaPath string, innerException Exception) ConfigLoadException
}
class GodotYamlConfigEnvironment {
+GodotYamlConfigEnvironment(isEditor Func~bool~, globalizePath Func~string,string~, enumerateDirectory Func~string,IReadOnlyList~GodotYamlConfigDirectoryEntry~~, fileExists Func~string,bool~, readAllBytes Func~string,byte[]~)
+IsEditor Func~bool~
+GlobalizePath Func~string,string~
+EnumerateDirectory Func~string,IReadOnlyList~GodotYamlConfigDirectoryEntry~?~
+FileExists Func~string,bool~
+ReadAllBytes Func~string,byte[]~
+Default GodotYamlConfigEnvironment
-EnumerateDirectoryCore(path string) IReadOnlyList~GodotYamlConfigDirectoryEntry~?
-FileExistsCore(path string) bool
-ReadAllBytesCore(path string) byte[]
}
class GodotYamlConfigDirectoryEntry {
+Name string
+IsDirectory bool
}
GodotYamlConfigLoader ..|> IConfigLoader
GodotYamlConfigLoader o--> GodotYamlConfigLoaderOptions
GodotYamlConfigLoader o--> GodotYamlConfigEnvironment
GodotYamlConfigLoader o--> YamlConfigLoader
GodotYamlConfigLoaderOptions "1" o--> "*" GodotYamlConfigTableSource
GodotYamlConfigEnvironment --> GodotYamlConfigDirectoryEntry
YamlConfigLoader ..> IConfigLoader
YamlConfigLoader ..> YamlConfigHotReloadOptions
YamlConfigLoader ..> IConfigRegistry
GodotYamlConfigLoader ..> IConfigRegistry
GodotYamlConfigLoader ..> IUnRegister
GodotYamlConfigLoader ..> ConfigLoadException
GodotYamlConfigLoader ..> ConfigLoadDiagnostic
GodotYamlConfigLoader ..> ConfigLoadFailureKind
GodotYamlConfigLoader ..> GodotYamlConfigDirectoryEntry
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
- 为Godot.FileAccess添加using别名以避免冲突 - 添加GFramework.Game.Config命名空间引用 - 添加NUnit.Framework测试框架引用 - 优化配置加载器的依赖管理 - 提升代码可读性和维护性 - 确保测试类的正确引用关系
|
@coderabbitai help |
ChatThere are 3 ways to chat with CodeRabbit:
CodeRabbit commands
Other keywords and placeholders
Status, support, documentation and community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/zh-CN/game/config-system.md`:
- Around line 316-317: 将“导出态：把当前注册会访问到的配置目录与 schema 文件同步到 `user://` 缓存，再交给底层
`YamlConfigLoader`”这句改为更顺畅的被动/说明式表述，例如“导出态：会将当前注册会访问到的配置目录与 schema 文件同步到
`user://` 缓存，再交给底层 `YamlConfigLoader`”，以避免读者误解动作主语；请在
docs/zh-CN/game/config-system.md 中定位包含该原句的段落并替换为建议表述（保留后半句 “再交给底层
`YamlConfigLoader`” 不变）。
In `@GFramework.Godot/Config/GodotYamlConfigLoader.cs`:
- Around line 29-31: Add XML documentation to the internal constructor
GodotYamlConfigLoader(GodotYamlConfigLoaderOptions, GodotYamlConfigEnvironment)
and to the GodotYamlConfigEnvironment and GodotYamlConfigDirectoryEntry types:
include <summary> describing why this internal abstraction exists (editor vs
export compatibility), <param> for each delegate explaining input constraints
(e.g., accepted path formats), when a delegate may legitimately return null,
<returns> conventions, <exception> cases for failure behavior, and a <remarks>
note clarifying the differences between Godot-style paths and filesystem paths
and any normalization rules; apply the same XML doc requirements to the related
members covered by the same abstraction (the other internal/public members that
implement these delegates) so all contracts around inputs, outputs, nullability,
and error handling are explicitly documented.
In `@GFramework.Godot/Config/GodotYamlConfigTableSource.cs`:
- Around line 14-39: The constructor of GodotYamlConfigTableSource currently
only checks for blank strings but must reject absolute paths and any '.' or '..'
path segments to prevent directory traversal; update the constructor (the
GodotYamlConfigTableSource(...) method that sets TableName, ConfigRelativePath,
SchemaRelativePath) to normalize and validate configRelativePath and
schemaRelativePath: ensure Path.IsPathRooted returns false, split the path into
segments and reject any "." or ".." segments (or any empties), and only accept a
clean relative path (for schemaRelativePath apply the same checks when
non-null); throw ArgumentException with a clear message if validation fails so
invalid inputs never reach GodotYamlConfigLoader/ResetDirectory.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 34c2ce19-50dc-4aaa-aab0-6366c9e5f54d
📒 Files selected for processing (7)
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.csGFramework.Godot.Tests/GFramework.Godot.Tests.csprojGFramework.Godot/Config/GodotYamlConfigLoader.csGFramework.Godot/Config/GodotYamlConfigLoaderOptions.csGFramework.Godot/Config/GodotYamlConfigTableSource.csGFramework.Godot/Properties/AssemblyInfo.csdocs/zh-CN/game/config-system.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Code Quality & Security
- GitHub Check: Analyze (C#)
🧰 Additional context used
📓 Path-based instructions (5)
**/*.csproj
📄 CodeRabbit inference engine (AGENTS.md)
**/*.csproj: Follow repository defaults:ImplicitUsingsdisabled,Nullableenabled,GenerateDocumentationFileenabled for shipped libraries,LangVersiongenerallypreviewin main libraries
Minimize new package dependencies; add them only when necessary and keep scope narrow
Files:
GFramework.Godot.Tests/GFramework.Godot.Tests.csproj
**/*.cs
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.cs: LoggerGenerator must automatically generate log fields and logging helper methods for classes decorated with [Log] attribute
PriorityGenerator must generate priority comparison implementations for classes decorated with [Priority] attribute
EnumExtensionsGenerator must generate enum extension capabilities for enums decorated with [GenerateEnumExtensions] attribute
ContextAwareGenerator must automatically implement IContextAware boilerplate logic for classes decorated with [ContextAware] attribute
**/*.cs: All public, protected, and internal types and members MUST include XML documentation comments (///) with<summary>,<param>,<returns>,<exception>, and<remarks>tags where applicable
XML documentation comments must explain intent, contract, and usage constraints instead of restating syntax
Add inline comments for non-trivial logic, concurrency/threading behavior, performance-sensitive paths, workarounds, compatibility constraints, edge cases, registration order, lifecycle sequencing, and generated code assumptions
Core framework components (Architecture, Module, System, Context, Registry, Service Module, Lifecycle types) MUST include high-level explanations of responsibilities, lifecycle, interactions with other components, why the abstraction exists, and when to use it instead of alternatives
Generated logic and source generator pipelines MUST explain what is generated, why it is generated, semantic assumptions the generator relies on, and any diagnostics or fallback behavior
Methods with non-trivial logic MUST document the core idea, key decisions, and edge case handling
Do not rely on implicit imports; declare every requiredusingexplicitly
Write null-safe code that respects nullable annotations instead of suppressing warnings by default
Use namespace patternGFramework.{Module}.{Feature}with PascalCase segments
Follow standard C# naming: Types/methods/properties/events/constants use PascalCase, interfaces useIprefix, parame...
Files:
GFramework.Godot/Properties/AssemblyInfo.csGFramework.Godot/Config/GodotYamlConfigLoaderOptions.csGFramework.Godot/Config/GodotYamlConfigTableSource.csGFramework.Godot/Config/GodotYamlConfigLoader.csGFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
docs/**/*
📄 CodeRabbit inference engine (CLAUDE.md)
Documentation must be located in docs/ directory with Chinese content in docs/zh-CN/
Files:
docs/zh-CN/game/config-system.md
{README.md,docs/**/*.md}
📄 CodeRabbit inference engine (AGENTS.md)
{README.md,docs/**/*.md}: Update the relevantREADME.mdordocs/page when behavior, setup steps, architecture guidance, or user-facing examples change
Keep code samples, package names, and command examples aligned with the current repository state
Prefer documenting behavior and design intent, not only API surface
For integration-oriented features such as AI-First config system, documentation MUST cover project directory layout, file conventions, required project/package wiring, minimal working usage example, and migration/compatibility notes
If an existing documentation page no longer reflects the current implementation, fixing the code without fixing the documentation is considered incomplete work
Do not rely on 'the code is self-explanatory' for framework features that consumers need to adopt; write the adoption path down so future users do not need to rediscover it from source
Files:
docs/zh-CN/game/config-system.md
docs/zh-CN/**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the corresponding user-facing integration documentation in
docs/zh-CN/in the same change
Files:
docs/zh-CN/game/config-system.md
🧠 Learnings (14)
📓 Common learnings
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to docs/zh-CN/**/*.md : When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the corresponding user-facing integration documentation in `docs/zh-CN/` in the same change
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Public API changes must be covered by unit or integration tests
Applied to files:
GFramework.Godot.Tests/GFramework.Godot.Tests.csprojGFramework.Godot/Properties/AssemblyInfo.csGFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Source generator changes MUST be covered by generator tests
Applied to files:
GFramework.Godot.Tests/GFramework.Godot.Tests.csprojGFramework.Godot/Properties/AssemblyInfo.csGFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.csproj : Minimize new package dependencies; add them only when necessary and keep scope narrow
Applied to files:
GFramework.Godot.Tests/GFramework.Godot.Tests.csproj
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Keep abstractions projects free of implementation details and engine-specific dependencies
Applied to files:
GFramework.Godot.Tests/GFramework.Godot.Tests.csproj
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Preserve snapshot-based verification patterns already used in the repository for source generator tests
Applied to files:
GFramework.Godot.Tests/GFramework.Godot.Tests.csprojGFramework.Godot/Properties/AssemblyInfo.csGFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-06T12:45:43.921Z
Learnt from: GeWuYou
Repo: GeWuYou/GFramework PR: 190
File: GFramework.Game/Config/GameConfigBootstrap.cs:1-3
Timestamp: 2026-04-06T12:45:43.921Z
Learning: In the GFramework repository (GeWuYou/GFramework), even though `ImplicitUsings` is disabled in the `.csproj` files, the project uses a manual `GlobalUsings.cs` file with `global using` directives to provide common System namespaces (e.g., System, System.Threading, System.Threading.Tasks) project-wide. Do not flag missing System-level `using` imports in C# files within this repository, as they are covered by GlobalUsings.cs.
Applied to files:
GFramework.Godot.Tests/GFramework.Godot.Tests.csproj
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Keep tests focused on observable behavior, not implementation trivia
Applied to files:
GFramework.Godot/Properties/AssemblyInfo.cs
📚 Learning: 2026-04-06T12:45:43.921Z
Learnt from: GeWuYou
Repo: GeWuYou/GFramework PR: 190
File: GFramework.Game/Config/GameConfigBootstrap.cs:1-3
Timestamp: 2026-04-06T12:45:43.921Z
Learning: In the GeWuYou/GFramework repository, C# files may omit explicit `using System*` imports because the project-wide `GlobalUsings.cs` (referenced via manual global `using` directives) supplies common namespaces (e.g., `System`, `System.Threading`, `System.Threading.Tasks`). During code review, do not flag missing `using System...` directives in `.cs` files as long as `GlobalUsings.cs` is present/used to provide those namespaces.
Applied to files:
GFramework.Godot/Properties/AssemblyInfo.csGFramework.Godot/Config/GodotYamlConfigLoaderOptions.csGFramework.Godot/Config/GodotYamlConfigTableSource.csGFramework.Godot/Config/GodotYamlConfigLoader.csGFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to docs/zh-CN/**/*.md : When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the corresponding user-facing integration documentation in `docs/zh-CN/` in the same change
Applied to files:
docs/zh-CN/game/config-system.md
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to {README.md,docs/**/*.md} : For integration-oriented features such as AI-First config system, documentation MUST cover project directory layout, file conventions, required project/package wiring, minimal working usage example, and migration/compatibility notes
Applied to files:
docs/zh-CN/game/config-system.md
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Regression fixes should include a test that fails before the fix and passes after it
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Reuse existing architecture test infrastructure when relevant: `ArchitectureTestsBase<T>`, `SyncTestArchitecture`, `AsyncTestArchitecture`
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Every non-trivial feature, bug fix, or behavior change MUST include tests or an explicit justification for why a test is not practical
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
🪛 GitHub Check: Build and Test
GFramework.Godot/Config/GodotYamlConfigLoader.cs
[failure] 461-461:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
[failure] 454-454:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
[failure] 461-461:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
[failure] 454-454:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
[failure] 461-461:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
[failure] 454-454:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
[failure] 461-461:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
[failure] 454-454:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
[failure] 461-461:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
[failure] 454-454:
'FileAccess' is an ambiguous reference between 'Godot.FileAccess' and 'System.IO.FileAccess'
🪛 LanguageTool
docs/zh-CN/game/config-system.md
[uncategorized] ~317-~317: 能愿动词不能成为‘把’字句、‘被’字句的谓语动词。应该是:"会把……当前"。
Context: ...://...")交给底层YamlConfigLoader- 导出态：把当前注册会访问到的配置目录与 schema 文件同步到user://` 缓存，再交给底...
(wa3)
🔇 Additional comments (1)
GFramework.Godot/Config/GodotYamlConfigLoader.cs (1)
451-462: 文件已正确处理FileAccess命名冲突，无需修改。第6行已明确包含别名导入：
using FileAccess = Godot.FileAccess;。这个别名导入使得FileAccess在此文件中清晰地引用Godot.FileAccess，完全消除了与System.IO中任何同名类型的歧义。代码在 455 和 462 行的使用正确，不存在编译失败的风险。无需使用Godot.FileAccess.FileExists(...)这样的完全限定形式。> Likely an incorrect or invalid review comment.
Greptile SummaryThis PR adds Key additions:
Confidence Score: 4/5Safe to merge after the two minor clean-ups; no logic bugs or security issues found. All previously-flagged issues have been resolved. Remaining findings are P2 style items: four unused global usings in GlobalUsings.cs and a missing tableName test case. Neither blocks correctness or safety; core logic, path-safety validation, editor/exported mode switching, and parent-before-child cache ordering are all correct and well-tested. GFramework.Godot.Tests/GlobalUsings.cs (unused imports) and GFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.cs (missing tableName validation test). Important Files Changed
Reviews (6): Last reviewed commit: "refactor(tests): 移除未使用的 Roslyn 分析器引用" | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@GFramework.Godot/Config/GodotYamlConfigLoader.cs`:
- Around line 141-157: The loop over _options.TableSources groups by
NormalizeRelativePath then resets the target directory for each group, causing
child directories (e.g., a/b) to be deleted if a parent (a) is processed later;
fix by ordering the groups by path depth ascending (parents before children)
with a stable sort before iterating so ResetDirectory runs for parents first;
implement this by replacing the foreach over .GroupBy(...) with iteration over
.GroupBy(...).OrderBy(g => g.Key.Count(c => c == Path.DirectorySeparatorChar ||
c == '/')) (or an equivalent depth-calculation) and keep using
NormalizeRelativePath, ResetDirectory, and CopyYamlFilesInDirectory as before;
apply the same ordering change to the other similar grouping loop that also
enumerates _options.TableSources.
- Around line 347-350: NormalizeRelativePath currently only normalizes slashes
and can allow "../" or absolute segments that escape the intended
LoaderRootPath; update NormalizeRelativePath (and calling sites that feed
ResetDirectory / File.WriteAllBytes) to validate inputs strictly: after
normalizing slashes and trimming leading slashes, reject null/empty inputs and
throw on any path containing ".." segments, any rooted/absolute path
(Path.IsPathRooted or leading '/' or drive-letter like "C:"), and any path with
volume/URI markers (':'); ensure callers use the validated result (or
catch/propagate the exception) before combining with LoaderRootPath so no
relative traversal or absolute paths can escape the cache directory.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: dd83c4a3-6523-407c-9dbe-f5cd4c35de59
📒 Files selected for processing (2)
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.csGFramework.Godot/Config/GodotYamlConfigLoader.cs
✅ Files skipped from review due to trivial changes (1)
- GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (C#)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.cs
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.cs: LoggerGenerator must automatically generate log fields and logging helper methods for classes decorated with [Log] attribute
PriorityGenerator must generate priority comparison implementations for classes decorated with [Priority] attribute
EnumExtensionsGenerator must generate enum extension capabilities for enums decorated with [GenerateEnumExtensions] attribute
ContextAwareGenerator must automatically implement IContextAware boilerplate logic for classes decorated with [ContextAware] attribute
**/*.cs: All public, protected, and internal types and members MUST include XML documentation comments (///) with<summary>,<param>,<returns>,<exception>, and<remarks>tags where applicable
XML documentation comments must explain intent, contract, and usage constraints instead of restating syntax
Add inline comments for non-trivial logic, concurrency/threading behavior, performance-sensitive paths, workarounds, compatibility constraints, edge cases, registration order, lifecycle sequencing, and generated code assumptions
Core framework components (Architecture, Module, System, Context, Registry, Service Module, Lifecycle types) MUST include high-level explanations of responsibilities, lifecycle, interactions with other components, why the abstraction exists, and when to use it instead of alternatives
Generated logic and source generator pipelines MUST explain what is generated, why it is generated, semantic assumptions the generator relies on, and any diagnostics or fallback behavior
Methods with non-trivial logic MUST document the core idea, key decisions, and edge case handling
Do not rely on implicit imports; declare every requiredusingexplicitly
Write null-safe code that respects nullable annotations instead of suppressing warnings by default
Use namespace patternGFramework.{Module}.{Feature}with PascalCase segments
Follow standard C# naming: Types/methods/properties/events/constants use PascalCase, interfaces useIprefix, parame...
Files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
🧠 Learnings (6)
📓 Common learnings
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to docs/zh-CN/**/*.md : When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the corresponding user-facing integration documentation in `docs/zh-CN/` in the same change
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : All public, protected, and internal types and members MUST include XML documentation comments (`///`) with `<summary>`, `<param>`, `<returns>`, `<exception>`, and `<remarks>` tags where applicable
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Methods with non-trivial logic MUST document the core idea, key decisions, and edge case handling
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Any change to public API, lifecycle semantics, module behavior, or extension points MUST update the related XML docs
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : XML documentation comments must explain intent, contract, and usage constraints instead of restating syntax
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-06T12:45:43.921Z
Learnt from: GeWuYou
Repo: GeWuYou/GFramework PR: 190
File: GFramework.Game/Config/GameConfigBootstrap.cs:1-3
Timestamp: 2026-04-06T12:45:43.921Z
Learning: In the GeWuYou/GFramework repository, C# files may omit explicit `using System*` imports because the project-wide `GlobalUsings.cs` (referenced via manual global `using` directives) supplies common namespaces (e.g., `System`, `System.Threading`, `System.Threading.Tasks`). During code review, do not flag missing `using System...` directives in `.cs` files as long as `GlobalUsings.cs` is present/used to provide those namespaces.
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
🔇 Additional comments (1)
GFramework.Godot/Config/GodotYamlConfigLoader.cs (1)
30-33: 内部 API 的 XML 契约文档仍缺失（与历史评论重复）。
GodotYamlConfigLoaderinternal 构造函数、GodotYamlConfigEnvironment、GodotYamlConfigDirectoryEntry及其关键成员/方法仍未补齐 XML 注释（含约束、返回约定、异常与备注）。Based on learnings: "Applies to **/*.cs : All public, protected, and internal types and members MUST include XML documentation comments (
///) with<summary>,<param>,<returns>,<exception>, and<remarks>tags where applicable".Also applies to: 379-410, 412-450, 467-469
- 新增配置系统概述和核心能力介绍 - 添加Schema和YAML配置文件格式示例 - 提供推荐目录结构和接入模板 - 详细说明Generator集成和运行时加载流程 - 介绍VS Code工具和热重载功能 - 添加Godot引擎桥接适配器文档 - 说明运行时校验行为和错误处理机制 - 提供Architecture模块集成模板 - 记录当前限制和未来规划评估
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
GFramework.Godot/Config/GodotYamlConfigLoader.cs (1)
160-176:⚠️ Potential issue | 🟠 Major按稳定顺序处理父目录，否则子目录缓存会被后续重置抹掉。
这里先
GroupBy(...)再直接遍历，顺序仍然取决于TableSources的首次出现位置。若输入里先有a/b、后有a，前者同步完成后，后者的ResetDirectory(root/a)会把刚写进去的root/a/b一并删掉，最终结果依赖配置声明顺序。🧭 建议修复
foreach (var group in _options.TableSources - .GroupBy(static source => NormalizeRelativePath(source.ConfigRelativePath), - StringComparer.Ordinal)) + .GroupBy(static source => NormalizeRelativePath(source.ConfigRelativePath), StringComparer.Ordinal) + .OrderBy(static group => group.Key.Count(static ch => ch == '/')) + .ThenBy(static group => group.Key, StringComparer.Ordinal)) { cancellationToken.ThrowIfCancellationRequested(); var representative = group.First();As per coding guidelines: "Preserve deterministic behavior in registries, lifecycle orchestration, and generated outputs".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@GFramework.Godot/Config/GodotYamlConfigLoader.cs` around lines 160 - 176, Grouped table source directories are iterated in input order, so a child directory like "a/b" may be processed before its parent "a", and the later ResetDirectory call on the parent can delete the child's output; to fix, sort the groups returned by GroupBy(...) so parents are handled before children (e.g., OrderBy on the normalized path depth or token count of NormalizeRelativePath(source.ConfigRelativePath)) before the foreach, keeping the existing representative/CombinePath/CombineAbsolutePath/ResetDirectory/CopyYamlFilesInDirectory usage and preserving stable tie-breakers (StringComparer.Ordinal) for equal depths.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@GFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.cs`:
- Around line 17-24: Add missing test cases that exercise backslash and
Windows-drive/schema path variants so IsSafeRelativePath's branches are covered;
in GodotYamlConfigTableSourceTests.cs update the existing parameterized test
(the TestCase lines shown) to include examples like "..\\outside", ".\\monster",
"monster\\..\\outside", "monster\\.\\child", "C:\\monster", "res:\\\\monster",
and "user:\\\\monster" (and their absolute/backslash combos) so the regression
that handles '\' and Windows drive letters/schemas fails before the fix and
passes afterwards; ensure you add the same set of cases for the other group
mentioned (lines 37-44) to fully cover both test groups.
---
Duplicate comments:
In `@GFramework.Godot/Config/GodotYamlConfigLoader.cs`:
- Around line 160-176: Grouped table source directories are iterated in input
order, so a child directory like "a/b" may be processed before its parent "a",
and the later ResetDirectory call on the parent can delete the child's output;
to fix, sort the groups returned by GroupBy(...) so parents are handled before
children (e.g., OrderBy on the normalized path depth or token count of
NormalizeRelativePath(source.ConfigRelativePath)) before the foreach, keeping
the existing
representative/CombinePath/CombineAbsolutePath/ResetDirectory/CopyYamlFilesInDirectory
usage and preserving stable tie-breakers (StringComparer.Ordinal) for equal
depths.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 47e1d840-51ff-44ba-9650-00c38618e823
📒 Files selected for processing (4)
GFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.csGFramework.Godot/Config/GodotYamlConfigLoader.csGFramework.Godot/Config/GodotYamlConfigTableSource.csdocs/zh-CN/game/config-system.md
✅ Files skipped from review due to trivial changes (1)
- docs/zh-CN/game/config-system.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Analyze (C#)
- GitHub Check: Build and Test
- GitHub Check: Code Quality & Security
🧰 Additional context used
📓 Path-based instructions (1)
**/*.cs
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.cs: LoggerGenerator must automatically generate log fields and logging helper methods for classes decorated with [Log] attribute
PriorityGenerator must generate priority comparison implementations for classes decorated with [Priority] attribute
EnumExtensionsGenerator must generate enum extension capabilities for enums decorated with [GenerateEnumExtensions] attribute
ContextAwareGenerator must automatically implement IContextAware boilerplate logic for classes decorated with [ContextAware] attribute
**/*.cs: All public, protected, and internal types and members MUST include XML documentation comments (///) with<summary>,<param>,<returns>,<exception>, and<remarks>tags where applicable
XML documentation comments must explain intent, contract, and usage constraints instead of restating syntax
Add inline comments for non-trivial logic, concurrency/threading behavior, performance-sensitive paths, workarounds, compatibility constraints, edge cases, registration order, lifecycle sequencing, and generated code assumptions
Core framework components (Architecture, Module, System, Context, Registry, Service Module, Lifecycle types) MUST include high-level explanations of responsibilities, lifecycle, interactions with other components, why the abstraction exists, and when to use it instead of alternatives
Generated logic and source generator pipelines MUST explain what is generated, why it is generated, semantic assumptions the generator relies on, and any diagnostics or fallback behavior
Methods with non-trivial logic MUST document the core idea, key decisions, and edge case handling
Do not rely on implicit imports; declare every requiredusingexplicitly
Write null-safe code that respects nullable annotations instead of suppressing warnings by default
Use namespace patternGFramework.{Module}.{Feature}with PascalCase segments
Follow standard C# naming: Types/methods/properties/events/constants use PascalCase, interfaces useIprefix, parame...
Files:
GFramework.Godot/Config/GodotYamlConfigTableSource.csGFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.csGFramework.Godot/Config/GodotYamlConfigLoader.cs
🧠 Learnings (15)
📓 Common learnings
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to docs/zh-CN/**/*.md : When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the corresponding user-facing integration documentation in `docs/zh-CN/` in the same change
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to {README.md,docs/**/*.md} : For integration-oriented features such as AI-First config system, documentation MUST cover project directory layout, file conventions, required project/package wiring, minimal working usage example, and migration/compatibility notes
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Validate external or user-controlled input before it reaches file system, serialization, reflection, code generation, or process boundaries
Applied to files:
GFramework.Godot/Config/GodotYamlConfigTableSource.csGFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Do not build command strings, file paths, type names, or generated code from untrusted input without strict validation or allow-listing
Applied to files:
GFramework.Godot/Config/GodotYamlConfigTableSource.csGFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-06T12:45:43.921Z
Learnt from: GeWuYou
Repo: GeWuYou/GFramework PR: 190
File: GFramework.Game/Config/GameConfigBootstrap.cs:1-3
Timestamp: 2026-04-06T12:45:43.921Z
Learning: In the GeWuYou/GFramework repository, C# files may omit explicit `using System*` imports because the project-wide `GlobalUsings.cs` (referenced via manual global `using` directives) supplies common namespaces (e.g., `System`, `System.Threading`, `System.Threading.Tasks`). During code review, do not flag missing `using System...` directives in `.cs` files as long as `GlobalUsings.cs` is present/used to provide those namespaces.
Applied to files:
GFramework.Godot/Config/GodotYamlConfigTableSource.csGFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.csGFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Source generator changes MUST be covered by generator tests
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Public API changes must be covered by unit or integration tests
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Regression fixes should include a test that fails before the fix and passes after it
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Preserve snapshot-based verification patterns already used in the repository for source generator tests
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Every non-trivial feature, bug fix, or behavior change MUST include tests or an explicit justification for why a test is not practical
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : All public, protected, and internal types and members MUST include XML documentation comments (`///`) with `<summary>`, `<param>`, `<returns>`, `<exception>`, and `<remarks>` tags where applicable
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Methods with non-trivial logic MUST document the core idea, key decisions, and edge case handling
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Any change to public API, lifecycle semantics, module behavior, or extension points MUST update the related XML docs
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : XML documentation comments must explain intent, contract, and usage constraints instead of restating syntax
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Add inline comments for non-trivial logic, concurrency/threading behavior, performance-sensitive paths, workarounds, compatibility constraints, edge cases, registration order, lifecycle sequencing, and generated code assumptions
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Preserve deterministic behavior in registries, lifecycle orchestration, and generated outputs
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
- 实现 GodotYamlConfigLoader 类，提供 YAML 配置加载适配层 - 支持编辑器态直接读取项目目录和导出态运行时缓存同步 - 添加 GodotYamlConfigEnvironment 抽象处理 Godot 路径和文件访问 - 实现配置文件同步机制，支持 YAML 和 schema 文件复制 - 提供热重载功能，在编辑器态下支持配置实时更新 - 添加完整的单元测试验证各种场景下的配置加载行为
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
GFramework.Godot/Config/GodotYamlConfigLoader.cs (1)
374-392:⚠️ Potential issue | 🟠 Major相对路径校验还需要拒绝
:，否则 Windows 上仍会落到文件系统异常。现在只拦截了 rooted path 和盘符前缀，像
schemas:bad/file.json这类带:的片段仍能通过NormalizeRelativePath。这些值继续进入Directory.CreateDirectory/File.WriteAllBytes时，会在 Windows 上直接炸成原生路径异常，等于又绕过了这里新增的防御式校验。As per coding guidelines: "Validate external or user-controlled input before it reaches file system, serialization, reflection, code generation, or process boundaries."
In .NET, how do Path.IsPathRooted and Windows file APIs treat relative paths containing ':' such as 'schemas:bad/file.json'?🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@GFramework.Godot/Config/GodotYamlConfigLoader.cs` around lines 374 - 392, NormalizeRelativePath currently misses segments containing ':' (e.g., "schemas:bad/file.json") which can still reach Directory.CreateDirectory/File.WriteAllBytes and cause native Windows path errors; update the validation in NormalizeRelativePath (and/or the segments.Any check) to reject any path or segment containing ':' (e.g., check normalizedPath and/or segments for ':' or use segments.Any(segment => segment.Contains(':'))), keeping the existing ArgumentException style and using nameof(relativePath) so such inputs are refused before hitting the filesystem; also ensure HasWindowsDrivePrefix logic remains unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@GFramework.Godot/Config/GodotYamlConfigLoader.cs`:
- Around line 174-175: The ResetDirectory/Directory.CreateDirectory calls in
GodotYamlConfigLoader.LoadAsync currently let raw IO exceptions escape; wrap the
filesystem operations (ResetDirectory,
Directory.CreateDirectory(targetDirectoryPath) and the CopyYamlFilesInDirectory
invocation) in try/catch blocks that catch IOException,
UnauthorizedAccessException (and optionally PathTooLongException) and rethrow a
ConfigLoadException with the caught exception as the InnerException and a clear
contextual message; apply the same pattern to the other similar filesystem
touches in this class (the ResetDirectory usage and the
Directory.CreateDirectory usage near the CopyYamlFilesInDirectory call and the
later directory-creation block) so callers always receive ConfigLoadException
instead of raw system exceptions.
- Around line 21-27: Update the XML docs for the new public constructor
GodotYamlConfigLoader(GodotYamlConfigLoaderOptions) and the EnableHotReload
member to include thrown exceptions and usage constraints: add <exception> tags
for ArgumentNullException (when options is null), ArgumentException (for invalid
options values), and InvalidOperationException (when environment/state disallows
initialization), and add a <remarks> entry stating that EnableHotReload can only
be set/used when the source directory is directly accessible (i.e.,
non-embedded/read-only sources); also mirror these doc updates on the related
overload/initializer (the ctor that takes GodotYamlConfigLoaderOptions and
GodotYamlConfigEnvironment) so all public entry points declare these exceptions
and the hot-reload constraint.
---
Duplicate comments:
In `@GFramework.Godot/Config/GodotYamlConfigLoader.cs`:
- Around line 374-392: NormalizeRelativePath currently misses segments
containing ':' (e.g., "schemas:bad/file.json") which can still reach
Directory.CreateDirectory/File.WriteAllBytes and cause native Windows path
errors; update the validation in NormalizeRelativePath (and/or the segments.Any
check) to reject any path or segment containing ':' (e.g., check normalizedPath
and/or segments for ':' or use segments.Any(segment => segment.Contains(':'))),
keeping the existing ArgumentException style and using nameof(relativePath) so
such inputs are refused before hitting the filesystem; also ensure
HasWindowsDrivePrefix logic remains unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 48aa3b80-8b12-4e12-bbe9-1d9d05512092
📒 Files selected for processing (2)
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.csGFramework.Godot/Config/GodotYamlConfigLoader.cs
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Build and Test
- GitHub Check: Code Quality & Security
- GitHub Check: Analyze (C#)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.cs
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.cs: LoggerGenerator must automatically generate log fields and logging helper methods for classes decorated with [Log] attribute
PriorityGenerator must generate priority comparison implementations for classes decorated with [Priority] attribute
EnumExtensionsGenerator must generate enum extension capabilities for enums decorated with [GenerateEnumExtensions] attribute
ContextAwareGenerator must automatically implement IContextAware boilerplate logic for classes decorated with [ContextAware] attribute
**/*.cs: All public, protected, and internal types and members MUST include XML documentation comments (///) with<summary>,<param>,<returns>,<exception>, and<remarks>tags where applicable
XML documentation comments must explain intent, contract, and usage constraints instead of restating syntax
Add inline comments for non-trivial logic, concurrency/threading behavior, performance-sensitive paths, workarounds, compatibility constraints, edge cases, registration order, lifecycle sequencing, and generated code assumptions
Core framework components (Architecture, Module, System, Context, Registry, Service Module, Lifecycle types) MUST include high-level explanations of responsibilities, lifecycle, interactions with other components, why the abstraction exists, and when to use it instead of alternatives
Generated logic and source generator pipelines MUST explain what is generated, why it is generated, semantic assumptions the generator relies on, and any diagnostics or fallback behavior
Methods with non-trivial logic MUST document the core idea, key decisions, and edge case handling
Do not rely on implicit imports; declare every requiredusingexplicitly
Write null-safe code that respects nullable annotations instead of suppressing warnings by default
Use namespace patternGFramework.{Module}.{Feature}with PascalCase segments
Follow standard C# naming: Types/methods/properties/events/constants use PascalCase, interfaces useIprefix, parame...
Files:
GFramework.Godot/Config/GodotYamlConfigLoader.csGFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
🧠 Learnings (12)
📓 Common learnings
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to docs/zh-CN/**/*.md : When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the corresponding user-facing integration documentation in `docs/zh-CN/` in the same change
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Any change to public API, lifecycle semantics, module behavior, or extension points MUST update the related XML docs
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : All public, protected, and internal types and members MUST include XML documentation comments (`///`) with `<summary>`, `<param>`, `<returns>`, `<exception>`, and `<remarks>` tags where applicable
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : XML documentation comments must explain intent, contract, and usage constraints instead of restating syntax
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Methods with non-trivial logic MUST document the core idea, key decisions, and edge case handling
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Add inline comments for non-trivial logic, concurrency/threading behavior, performance-sensitive paths, workarounds, compatibility constraints, edge cases, registration order, lifecycle sequencing, and generated code assumptions
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Validate external or user-controlled input before it reaches file system, serialization, reflection, code generation, or process boundaries
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Do not build command strings, file paths, type names, or generated code from untrusted input without strict validation or allow-listing
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-06T12:45:43.921Z
Learnt from: GeWuYou
Repo: GeWuYou/GFramework PR: 190
File: GFramework.Game/Config/GameConfigBootstrap.cs:1-3
Timestamp: 2026-04-06T12:45:43.921Z
Learning: In the GeWuYou/GFramework repository, C# files may omit explicit `using System*` imports because the project-wide `GlobalUsings.cs` (referenced via manual global `using` directives) supplies common namespaces (e.g., `System`, `System.Threading`, `System.Threading.Tasks`). During code review, do not flag missing `using System...` directives in `.cs` files as long as `GlobalUsings.cs` is present/used to provide those namespaces.
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.csGFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Public API changes must be covered by unit or integration tests
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Regression fixes should include a test that fails before the fix and passes after it
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Source generator changes MUST be covered by generator tests
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
🔇 Additional comments (1)
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs (1)
52-222: 这组回归用例补得很到位。导出态缓存同步、编辑器态直读、热重载开关、父/子目录顺序，以及损坏元数据路径这几条关键行为都覆盖到了，后续再改加载器时更容易第一时间发现回归。
Based on learnings: "Public API changes must be covered by unit or integration tests" and "Regression fixes should include a test that fails before the fix and passes after it."
- 为构造函数添加ArgumentNullException和ArgumentException异常说明 - 为EnableHotReload方法添加InvalidOperationException异常说明 - 重构ResetDirectory方法以捕获目录操作异常并包装为ConfigLoadException - 添加detail参数到CreateConfigLoadException方法用于提供更详细的错误信息 - 新增单元测试验证运行时缓存目录重置失败时的异常处理 - 添加GodotYamlConfigTableSourceTests测试类验证安全相对路径约束
- 添加了详细的 XML 文档注释说明方法功能和参数 - 补充了异常情况的详细说明包括 ArgumentNullException 和 ConfigLoadException - 添加了关于运行时缓存同步执行原因的技术备注 - 保留了原有的继承特性标记并添加了完整的文档结构
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@GFramework.Godot/Config/GodotYamlConfigLoader.cs`:
- Around line 596-612: Check the result of directory.ListDirBegin() and handle
non-OK Godot.Error values: call var err = directory.ListDirBegin(); if err !=
Error.Ok return null (or propagate the error) before calling GetNext(), and
ensure directory.ListDirEnd() is still called when appropriate; update the code
around the directory variable and the loop that creates
List<GodotYamlConfigDirectoryEntry> (which uses GetNext() and CurrentIsDir()) so
failures return null (matching DirAccess.Open failure semantics) rather than an
empty list.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 5b8663d9-1d53-4f3f-b660-0f44b3a22726
📒 Files selected for processing (3)
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.csGFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.csGFramework.Godot/Config/GodotYamlConfigLoader.cs
🚧 Files skipped from review as they are similar to previous changes (1)
- GFramework.Godot.Tests/Config/GodotYamlConfigTableSourceTests.cs
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Code Quality & Security
- GitHub Check: Analyze (C#)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.cs
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.cs: LoggerGenerator must automatically generate log fields and logging helper methods for classes decorated with [Log] attribute
PriorityGenerator must generate priority comparison implementations for classes decorated with [Priority] attribute
EnumExtensionsGenerator must generate enum extension capabilities for enums decorated with [GenerateEnumExtensions] attribute
ContextAwareGenerator must automatically implement IContextAware boilerplate logic for classes decorated with [ContextAware] attribute
**/*.cs: All public, protected, and internal types and members MUST include XML documentation comments (///) with<summary>,<param>,<returns>,<exception>, and<remarks>tags where applicable
XML documentation comments must explain intent, contract, and usage constraints instead of restating syntax
Add inline comments for non-trivial logic, concurrency/threading behavior, performance-sensitive paths, workarounds, compatibility constraints, edge cases, registration order, lifecycle sequencing, and generated code assumptions
Core framework components (Architecture, Module, System, Context, Registry, Service Module, Lifecycle types) MUST include high-level explanations of responsibilities, lifecycle, interactions with other components, why the abstraction exists, and when to use it instead of alternatives
Generated logic and source generator pipelines MUST explain what is generated, why it is generated, semantic assumptions the generator relies on, and any diagnostics or fallback behavior
Methods with non-trivial logic MUST document the core idea, key decisions, and edge case handling
Do not rely on implicit imports; declare every requiredusingexplicitly
Write null-safe code that respects nullable annotations instead of suppressing warnings by default
Use namespace patternGFramework.{Module}.{Feature}with PascalCase segments
Follow standard C# naming: Types/methods/properties/events/constants use PascalCase, interfaces useIprefix, parame...
Files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.csGFramework.Godot/Config/GodotYamlConfigLoader.cs
🧠 Learnings (15)
📓 Common learnings
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to docs/zh-CN/**/*.md : When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the corresponding user-facing integration documentation in `docs/zh-CN/` in the same change
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Public API changes must be covered by unit or integration tests
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Regression fixes should include a test that fails before the fix and passes after it
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Source generator changes MUST be covered by generator tests
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.Tests.cs : Preserve snapshot-based verification patterns already used in the repository for source generator tests
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs
📚 Learning: 2026-04-06T12:45:43.921Z
Learnt from: GeWuYou
Repo: GeWuYou/GFramework PR: 190
File: GFramework.Game/Config/GameConfigBootstrap.cs:1-3
Timestamp: 2026-04-06T12:45:43.921Z
Learning: In the GeWuYou/GFramework repository, C# files may omit explicit `using System*` imports because the project-wide `GlobalUsings.cs` (referenced via manual global `using` directives) supplies common namespaces (e.g., `System`, `System.Threading`, `System.Threading.Tasks`). During code review, do not flag missing `using System...` directives in `.cs` files as long as `GlobalUsings.cs` is present/used to provide those namespaces.
Applied to files:
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.csGFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Any change to public API, lifecycle semantics, module behavior, or extension points MUST update the related XML docs
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : All public, protected, and internal types and members MUST include XML documentation comments (`///`) with `<summary>`, `<param>`, `<returns>`, `<exception>`, and `<remarks>` tags where applicable
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : XML documentation comments must explain intent, contract, and usage constraints instead of restating syntax
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Methods with non-trivial logic MUST document the core idea, key decisions, and edge case handling
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Add inline comments for non-trivial logic, concurrency/threading behavior, performance-sensitive paths, workarounds, compatibility constraints, edge cases, registration order, lifecycle sequencing, and generated code assumptions
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Preserve deterministic behavior in registries, lifecycle orchestration, and generated outputs
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Validate external or user-controlled input before it reaches file system, serialization, reflection, code generation, or process boundaries
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : Do not build command strings, file paths, type names, or generated code from untrusted input without strict validation or allow-listing
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
📚 Learning: 2026-04-10T09:05:17.290Z
Learnt from: CR
Repo: GeWuYou/GFramework PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T09:05:17.290Z
Learning: Applies to **/*.cs : If a framework abstraction changes meaning or intended usage, update the explanatory comments in code as part of the same change
Applied to files:
GFramework.Godot/Config/GodotYamlConfigLoader.cs
🔇 Additional comments (9)
GFramework.Godot/Config/GodotYamlConfigLoader.cs (4)
1-85: 构造函数和初始化逻辑实现良好。构造函数正确地：
- 使用
ArgumentNullException.ThrowIfNull验证空参数- 验证
SourceRootPath和RuntimeCacheRootPath不为空白- 完整的 XML 文档包含所有
<exception>标签- 通过
GodotYamlConfigEnvironment抽象解耦了 Godot 引擎依赖之前审查中提到的异常文档要求已完整实现。
185-227: 运行时缓存同步逻辑正确处理了父/子目录顺序。
SynchronizeRuntimeCache通过.OrderBy(static group => CountPathDepth(group.Key))确保父目录先于子目录被重置，避免了之前审查中指出的缓存丢失问题。路径深度计算简单有效。
409-432: 路径遍历防护实现完整。
NormalizeRelativePath方法正确拒绝：
- 以
/开头的路径- Godot 特殊路径前缀（
res://、user://）- Windows 驱动器前缀
- 包含
.或..的路径段- 通过
Path.IsPathRooted检测的其他根路径这满足了编码指南中"验证外部或用户控制的输入，防止其到达文件系统边界"的要求。
475-659: 环境抽象和目录条目类型文档完整。
GodotYamlConfigEnvironment和GodotYamlConfigDirectoryEntry现在包含完整的 XML 文档，解释了：
- 为什么需要该抽象（编辑器态与导出态的访问差异）
- 各委托的输入约束和返回约定
EnumerateDirectory返回null的语义- Godot 路径与普通路径的处理差异
这满足了之前审查中对内部类型文档的要求。
GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs (5)
15-47: 测试夹具设置和清理实现正确。使用
Guid.NewGuid()创建独立的临时目录确保测试隔离，TearDown正确清理资源。这是可靠测试实践的良好示例。
56-106: 导出态与编辑器态行为测试覆盖全面。两个测试用例正确验证了：
- 导出态（
isEditor: false）：文件同步到缓存、CanEnableHotReload == false、LoaderRootPath指向缓存目录- 编辑器态（
isEditor: true）：直接使用项目目录、CanEnableHotReload == true、不创建缓存目录断言覆盖了加载器状态和注册表内容两个维度。
183-203: 缓存目录重置失败的错误处理测试设计巧妙。第 187 行通过
WriteFile(_userRoot, "config_cache", "occupied")在缓存路径创建一个文件而非目录，当加载器尝试在该路径下创建子目录时会触发IOException。测试正确验证了：
- 异常类型为
ConfigLoadExceptionFailureKind为ConfigFileReadFailed- 诊断信息包含表名和路径
- 内部异常为
IOException
208-248: 防御式路径验证测试使用反射绕过构造函数约束。使用
RuntimeHelpers.GetUninitializedObject和反射设置字段来创建"损坏的"配置源对象是测试防御式代码的有效方法。这验证了即使调用方绕过了GodotYamlConfigTableSource的公开构造校验，加载器内部的NormalizeRelativePath仍会拒绝危险路径。测试期望
ParamName == "relativePath"与NormalizeRelativePath中的nameof(relativePath)参数一致。
389-424: 反射辅助方法文档清晰。
CreateUnsafeTableSource和SetAutoPropertyBackingField的 XML 文档清楚说明了这些方法的用途——构造绕过验证的测试对象。这种测试策略能有效验证加载器的纵深防御能力。
- 将Godot.FileAccess重命名为FileAccess以避免命名冲突 - 优化了配置加载器中的文件操作引用 - 提高了代码的可读性和维护性
- 在 GodotYamlConfigLoader 中增加对路径中冒号字符的验证，防止 Windows 无效名称和 ADS 类似语法 - 新增 GodotYamlConfigTableSource 类用于描述配置表来源信息，并实现安全路径验证 - 添加对配置路径和 schema 路径的严格安全检查，拒绝包含根路径、遍历标记或冒号字符的路径 - 扩展测试用例覆盖多种不安全路径场景，包括路径遍历、绝对路径前缀和冒号字符 - 为新功能添加完整的单元测试验证安全路径验证逻辑
- 将Godot.FileAccess别名为FileAccess以提高代码可读性 - 保持现有功能不变，仅优化命名空间引用方式
- 在 GodotYamlConfigLoaderTests 中添加 GFramework.Game.Config 引用 - 从 GodotYamlConfigTableSourceTests 中移除未使用的 System 引用 - 新增 GlobalUsings.cs 文件统一管理所有全局引用 - 将常用的系统命名空间配置为全局引用以减少重复导入 - 优化测试代码的引用管理和项目结构
- 添加了 ListDirBegin 方法的错误检查 - 在遇到错误时返回 null 避免异常 - 确保目录遍历前检查操作状态
- 新增游戏内容配置系统详细文档，涵盖 YAML 配置、JSON Schema 结构描述 - 添加运行时只读查询、Source Generator 类型生成等功能说明 - 提供推荐目录结构、Schema 示例和 YAML 示例配置 - 添加 VS Code 插件配置浏览、校验和表单编辑功能介绍 - 提供 Godot 文本配置桥接、运行时读取模板和 Architecture 接入指南 - 说明热重载、跨表引用、查询辅助等高级功能使用方法 - 添加开发期工具和当前限制说明，提供完整的配置系统接入流程
- 添加事件抽象依赖项到YAML配置加载器 - 添加YamlDotNet序列化库依赖项 - 为Godot平台配置文件访问添加别名引用 - 在测试文件中添加配置依赖项引用
- 从 GlobalUsings.cs 中删除 Microsoft.CodeAnalysis 的全局引用 - 清理测试项目中不再需要的依赖项
1 participant
Summary by Sourcery
引入一个针对 Godot 的 YAML 配置加载桥接器，并在游戏配置系统中文档化其用法。
New Features:
GodotYamlConfigLoader，用于在使用res://和user://路径的 Godot 项目中适配基于 YAML 的游戏配置。GodotYamlConfigLoaderOptions和GodotYamlConfigTableSource，用于配置 Godot YAML 表数据源以及运行时缓存行为。Documentation:
Tests:
GodotYamlConfigLoader在编辑器和类导出环境中的行为，包括运行时缓存同步与热重载可用性。Original summary in English
Summary by Sourcery
Introduce a Godot-specific YAML configuration loading bridge and document its usage within the game config system.
New Features:
Documentation:
Tests:
Summary by CodeRabbit