Merge pull request #316 from GeWuYou/docs/godot-logging-composition-archive

docs(godot): 归档 Godot logging 主题

ai-plan/public/README.md

@@ -42,11 +42,6 @@ help the current worktree land on the right recovery documents without scanning
   - Purpose: migrate release version calculation from fixed patch bumps to semantic-release while keeping the existing tag-driven NuGet publish flow.
   - Tracking: `ai-plan/public/semantic-release-versioning/todos/semantic-release-versioning-tracking.md`
   - Trace: `ai-plan/public/semantic-release-versioning/traces/semantic-release-versioning-trace.md`
-- `godot-logging-core-sink`
-  - Purpose: evaluate and implement the next Godot logging stage by unifying Godot output with the Core logging
-    appender / sink model instead of expanding a separate Godot-only logging pipeline.
-  - Tracking: `ai-plan/public/godot-logging-core-sink/todos/godot-logging-core-sink-tracking.md`
-  - Trace: `ai-plan/public/godot-logging-core-sink/traces/godot-logging-core-sink-trace.md`
 
 ## Worktree To Active Topic Map
 
@@ -67,9 +62,6 @@ help the current worktree land on the right recovery documents without scanning
 - Branch: `feat/semantic-release-versioning`
   - Worktree hint: `GFramework`
   - Priority 1: `semantic-release-versioning`
-- Branch: `feat/godot-logging-core-sink`
-  - Worktree hint: `GFramework`
-  - Priority 1: `godot-logging-core-sink`
 - Branch: `docs/sdk-update-documentation`
   - Worktree hint: `GFramework-update-documentation`
   - Priority 1: `documentation-full-coverage-governance`

ai-plan/public/archive/godot-logging-core-sink/todos/godot-logging-core-sink-tracking.md

@@ -5,16 +5,18 @@
 在 `GFramework.Godot.Logging` 已完成宿主便利层收口后，评估并推进 Godot 输出与 `GFramework.Core` 日志扩展点的统一。
 本主题优先判断是否应把 Godot 输出沉淀为 Core 可组合的 appender / sink，而不是继续扩张 Godot-only logging 管线。
 
-## 当前恢复点
+## 完成状态
 
-- 恢复点编号：`GODOT-LOGGING-CORE-SINK-RP-004`
-- 当前阶段：`PR review follow-up 复查已验证`
-- 当前焦点：
+- 恢复点编号：`GODOT-LOGGING-CORE-SINK-RP-005`
+- 当前阶段：`已完成并归档`
+- 完成结论：
   - `GFramework.Godot.Logging.GodotLogAppender` 已作为 Core `ILogAppender` 的 Godot 宿主落点落地
   - `GodotLogger` 保留原有 `ILogger` 入口，但底层输出委托给 appender
   - Godot / Core logging 文档已说明 provider 与 appender 的组合边界
+  - 已补充 `CompositeLogger + GodotLogAppender + AsyncLogAppender + FileAppender` 的配置化 factory 示例
   - PR #315 最新 AI review 中仍适用的测试稳定性、dead private wrapper、boot index 与 trace heading 问题已处理
   - 最新 CodeRabbit outside-diff 复查指出的反射测试诊断不清晰问题已处理
+  - 本主题已从 `ai-plan/public/README.md` 的 active topic 与 worktree map 移除
 
 ## 已知输入
 
@@ -23,7 +25,7 @@
   - `GFramework.Core` 仍是主日志框架
   - `GFramework.Godot.Logging` 已补齐 `GodotLog`、延迟 logger、配置发现、热重载和结构化属性渲染
   - 下一阶段应新建 topic 评估 Godot sink / appender 化，而不是继续在归档主题内扩张
-- 当前分支同时承载归档收尾与本 active topic 启动，避免为纯归档维护单独开 PR
+- `ai-libs/GodotLogger` 继续作为只读外部参考；本主题不引入 `Microsoft.Extensions.Logging` provider / builder 生态
 
 ## 待办
 
@@ -33,7 +35,8 @@
 4. 已完成：补充 `GodotLogAppender` targeted tests 与 `docs/zh-CN/` adoption guidance
 5. 已完成：处理 PR #315 最新 review follow-up，移除默认 boot index 的 archived topics 区块并消除 trace 重复 heading
 6. 已完成：处理最新 CodeRabbit outside-diff 反馈，显式断言反射目标与返回类型以改善测试失败定位
-7. 待确认：是否还需要在后续阶段补一个配置化 factory 示例，把 `GodotLogAppender` 与文件 / async appender 显式组合
+7. 已完成：补充配置化 factory 示例，把 `GodotLogAppender` 与文件 / async appender 显式组合
+8. 已完成：归档 `godot-logging-core-sink` 主题，默认 boot 不再加载本主题
 
 ## 验证
 
@@ -59,9 +62,15 @@
 - `dotnet format GFramework.sln --verify-no-changes --no-restore`
   - 结果：失败
   - 备注：失败集中在仓库既有的 whitespace、final newline 与 charset 诊断，跨 `GFramework.Core`、`GFramework.Cqrs`、`GFramework.Game.Abstractions` 等未触碰项目；本轮改动用 scoped format 验证
+- `dotnet build GFramework.Godot -c Release`
+  - 结果：通过，`0 warning / 0 error`
+  - 备注：2026-05-03 在短分支 `docs/godot-logging-composition-archive` 串行重跑
+- `dotnet test GFramework.Godot.Tests -c Release`
+  - 结果：通过，`75 passed / 0 failed / 0 skipped`
+  - 备注：2026-05-03 在短分支 `docs/godot-logging-composition-archive` 串行重跑
 
-## 下一步
+## 归档说明
 
-1. 提交最新 PR review follow-up
-2. 等待 PR #315 复查并确认 CodeRabbit outside-diff 反馈是否关闭
-3. 如继续扩展本主题，优先评估是否需要示例化 `CompositeLogger + GodotLogAppender + FileAppender`，而不是新增 API
+1. 本主题已随 PR #315 合并到 `origin/main`
+2. 默认 boot 索引不再指向本主题
+3. 后续 Logger 演进只有在出现真实消费项目痛点时再新建 active topic；默认不保留长期 Logger 分支

ai-plan/public/archive/godot-logging-core-sink/traces/godot-logging-core-sink-trace.md

@@ -115,3 +115,29 @@
 
 1. 提交最新 PR review follow-up
 2. 等待 PR #315 复查，确认 CodeRabbit outside-diff 反馈是否关闭
+
+### RP-005 组合示例与主题归档
+
+- PR #315 已合并，当前短分支从 `origin/main` 创建，用于收口最后的文档示例与 active topic 归档
+- 复核结论：
+  - `ai-libs/GodotLogger` 的宿主便利层能力已由 `godot-logging-compliance-polish` 吸收并归档
+  - 本主题已把 Godot 输出落到 Core `ILogAppender`，无需新增第二套 sink API
+  - 仅剩有价值的补强是示例化 Core appender 组合，而不是继续扩展 Logger 框架代码
+- 已实施：
+  - 在 `docs/zh-CN/core/logging.md` 补充 `GodotLogAppender + AsyncLogAppender + FileAppender` 组合 provider 示例
+  - 在 `docs/zh-CN/godot/logging.md` 补充 Godot 宿主下的组合接入路径，并说明 `user://` 路径需先转换为文件系统路径
+  - 将 `godot-logging-core-sink` 移入 `ai-plan/public/archive/`
+  - 从 `ai-plan/public/README.md` 移除本主题 active topic 与 `feat/godot-logging-core-sink` 分支映射
+
+### RP-005 验证
+
+- 首次并行运行 `dotnet build GFramework.Godot -c Release` 与 `dotnet test GFramework.Godot.Tests -c Release` 时，
+  build 命中 MSBuild 输出文件锁竞争；随后改为串行重跑同样的 direct 命令作为最终结果
+- `dotnet build GFramework.Godot -c Release`
+  - 结果：通过，`0 warning / 0 error`
+- `dotnet test GFramework.Godot.Tests -c Release`
+  - 结果：通过，`75 passed / 0 failed / 0 skipped`
+
+### RP-005 下一步
+
+1. 提交短分支

docs/zh-CN/core/logging.md

@@ -83,6 +83,64 @@ using (LogContext.Push("RequestId", requestId))
 `GFramework.Godot.Logging.GodotLogAppender`，再用 `CompositeLogger` 或自定义 factory 把它和文件、JSON、异步输出等
 Core 组件组合在同一条调用面下。
 
+## 组合多个输出目标
+
+需要同时写入宿主控制台和文件时，保留业务侧 `ILogger` 调用面不变，替换 provider 即可。下面的 provider 会为每个
+logger 创建一个 `CompositeLogger`，并把同步的 Godot 控制台输出和异步文件输出组合在一起：
+
+```csharp
+using GFramework.Core.Abstractions.Logging;
+using GFramework.Core.Logging;
+using GFramework.Core.Logging.Appenders;
+using GFramework.Core.Logging.Formatters;
+using GFramework.Godot.Logging;
+
+public sealed class GodotCompositeLoggerFactoryProvider : ILoggerFactoryProvider
+{
+    private readonly GodotLogAppender _godotAppender = new();
+    private readonly AsyncLogAppender _fileAppender;
+
+    public GodotCompositeLoggerFactoryProvider(string filePath)
+    {
+        _fileAppender = new AsyncLogAppender(new FileAppender(filePath, new DefaultLogFormatter()));
+    }
+
+    public LogLevel MinLevel { get; set; } = LogLevel.Info;
+
+    public ILogger CreateLogger(string name)
+    {
+        return new CompositeLogger(
+            name,
+            MinLevel,
+            _godotAppender,
+            _fileAppender);
+    }
+}
+```
+
+把 provider 挂到架构配置时，传入已经解析好的普通文件系统路径：
+
+```csharp
+using GFramework.Core.Abstractions.Logging;
+using GFramework.Core.Abstractions.Properties;
+using GFramework.Core.Architectures;
+
+var logPath = "path/to/game.log";
+var configuration = new ArchitectureConfiguration
+{
+    LoggerProperties = new LoggerProperties
+    {
+        LoggerFactoryProvider = new GodotCompositeLoggerFactoryProvider(logPath)
+        {
+            MinLevel = LogLevel.Debug
+        }
+    }
+};
+```
+
+`GodotLogAppender` 只负责 Godot 控制台落点；文件生命周期、异步缓冲、formatter 与过滤规则仍然来自 Core logging 组件。
+Godot 项目的 `user://` 路径解析方式见 [Godot 日志集成](../godot/logging.md#_3-组合-godot-控制台和文件输出)。
+
 ## 什么时候该换 provider
 
 下面这些场景通常不该只靠改 `MinLevel`：

docs/zh-CN/godot/logging.md

@@ -216,11 +216,72 @@ public partial class SettingsPanel : Control
 如果你已经在用 `GFramework.Core.SourceGenerators`，也可以继续让 `[Log]` 生成字段。Godot provider 只改变输出落点，
 不会改变 `[Log]` 的生成契约。需要静态字段延迟初始化时，也可以直接用 `GodotLog.CreateLogger<T>()`。
 
-### 3. Scene / UI 迁移日志会自动复用同一套 provider
+### 3. 组合 Godot 控制台和文件输出
+
+如果项目需要在 Godot 控制台显示日志，同时把完整日志写到文件，不需要扩展 `GodotLogger` 本身。用自定义
+`ILoggerFactoryProvider` 返回 `CompositeLogger`，把 `GodotLogAppender` 和 Core appender 组合起来即可：
+
+```csharp
+using GFramework.Core.Abstractions.Logging;
+using GFramework.Core.Logging;
+using GFramework.Core.Logging.Appenders;
+using GFramework.Core.Logging.Formatters;
+using GFramework.Godot.Logging;
+
+public sealed class GodotCompositeLoggerFactoryProvider : ILoggerFactoryProvider
+{
+    private readonly GodotLogAppender _godotAppender = new();
+    private readonly AsyncLogAppender _fileAppender;
+
+    public GodotCompositeLoggerFactoryProvider(string filePath)
+    {
+        _fileAppender = new AsyncLogAppender(new FileAppender(filePath, new DefaultLogFormatter()));
+    }
+
+    public LogLevel MinLevel { get; set; } = LogLevel.Info;
+
+    public ILogger CreateLogger(string name)
+    {
+        return new CompositeLogger(
+            name,
+            MinLevel,
+            _godotAppender,
+            _fileAppender);
+    }
+}
+```
+
+挂到架构配置时，先把 Godot 的 `user://` 路径转换为普通文件系统路径：
+
+```csharp
+using GFramework.Core.Abstractions.Logging;
+using GFramework.Core.Abstractions.Properties;
+using GFramework.Core.Architectures;
+using Godot;
+
+var logPath = ProjectSettings.GlobalizePath("user://logs/game.log");
+var architecture = new GameArchitecture(
+    new ArchitectureConfiguration
+    {
+        LoggerProperties = new LoggerProperties
+        {
+            LoggerFactoryProvider = new GodotCompositeLoggerFactoryProvider(logPath)
+            {
+                MinLevel = LogLevel.Debug
+            }
+        }
+    },
+    environment);
+```
+
+这种接法适合“Godot 控制台 + 文件落盘”的宿主组合。JSON formatter、namespace filter、rolling file 或更复杂的
+异步策略继续使用 Core logging 组件，不需要在 `GFramework.Godot.Logging` 里新增一套专用 API。
+
+### 4. Scene / UI 迁移日志会自动复用同一套 provider
 
 `GFramework.Game.Scene.Handler.LoggingTransitionHandler` 和
 `GFramework.Game.UI.Handler.LoggingTransitionHandler` 都是普通 `ILogger` 使用者。只要当前架构挂的是
-`GodotLoggerFactoryProvider`，这些迁移日志就会直接进 Godot 控制台。
+`GodotLoggerFactoryProvider` 或包含 `GodotLogAppender` 的自定义 provider，这些迁移日志就会直接进 Godot 控制台。
 
 ```csharp
 using GFramework.Game.Scene.Handler;