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

docs(godot): 归档 Godot logging 主题

GFramework.Godot.Tests/Logging/GodotLogAppenderTests.cs

@@ -0,0 +1,85 @@
+using System;
+using System.Collections.Generic;
+using GFramework.Core.Abstractions.Logging;
+using GFramework.Godot.Logging;
+
+namespace GFramework.Godot.Tests.Logging;
+
+/// <summary>
+///     Verifies the Godot appender edge that adapts Core log entries to Godot output rendering.
+/// </summary>
+[TestFixture]
+public sealed class GodotLogAppenderTests
+{
+    /// <summary>
+    ///     Verifies that the appender renders Core log entry data and merged structured properties.
+    /// </summary>
+    [Test]
+    public void Render_Should_Use_Core_LogEntry_And_Merged_Properties()
+    {
+        LogContext.Clear();
+        using var sceneContext = LogContext.Push("Scene", "Boot");
+        var appender = new GodotLogAppender(new GodotLoggerOptions
+        {
+            Mode = GodotLoggerMode.Release,
+            ReleaseOutputTemplate = "{timestamp:yyyyMMdd}|{level:u3}|{category}|{message}{properties}"
+        });
+        var entry = new LogEntry(
+            new DateTime(2026, 5, 3, 4, 5, 6, DateTimeKind.Utc),
+            LogLevel.Info,
+            "Game.Services.Inventory",
+            "Ready",
+            null,
+            new Dictionary<string, object?>(StringComparer.Ordinal)
+            {
+                ["   "] = "ignored",
+                ["Score"] = 12.5m
+            });
+
+        var result = appender.Render(entry);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(result, Does.StartWith("20260503|INF|Game.Services.Inventory|Ready | "));
+            Assert.That(result, Does.Contain("Scene=Boot"));
+            Assert.That(result, Does.Contain("Score=12.5"));
+        });
+    }
+
+    /// <summary>
+    ///     Verifies that dynamic option providers are evaluated for each rendered log entry.
+    /// </summary>
+    [Test]
+    public void Render_Should_Use_Latest_Options_From_Provider()
+    {
+        var options = new GodotLoggerOptions
+        {
+            Mode = GodotLoggerMode.Release,
+            ReleaseOutputTemplate = "[release] {message}"
+        };
+        var appender = new GodotLogAppender(() => options);
+        var entry = new LogEntry(
+            DateTime.UtcNow,
+            LogLevel.Warning,
+            "Game",
+            "Reloaded",
+            null,
+            null);
+
+        var releaseResult = appender.Render(entry);
+
+        options = new GodotLoggerOptions
+        {
+            Mode = GodotLoggerMode.Debug,
+            DebugOutputTemplate = "[debug] {message}"
+        };
+
+        var debugResult = appender.Render(entry);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(releaseResult, Is.EqualTo("[release] Reloaded"));
+            Assert.That(debugResult, Is.EqualTo("[debug] Reloaded"));
+        });
+    }
+}

GFramework.Godot.Tests/Logging/GodotLoggerSettingsLoaderTests.cs

@@ -192,9 +192,11 @@ public sealed class GodotLoggerSettingsLoaderTests
     [Test]
     public void StructuredProperties_Should_Skip_Blank_Keys_And_Trim_Valid_Keys()
     {
-        var formatProperties = typeof(GodotLogger).GetMethod(
-            "FormatProperties",
+        var toPropertiesDictionary = typeof(GodotLogger).GetMethod(
+            "ToPropertiesDictionary",
             BindingFlags.NonPublic | BindingFlags.Static);
+        Assert.That(toPropertiesDictionary, Is.Not.Null, "Unable to reflect GodotLogger.ToPropertiesDictionary.");
+
         var properties = new (string Key, object? Value)[]
         {
             (null!, "ignored"),
@@ -202,7 +204,10 @@ public sealed class GodotLoggerSettingsLoaderTests
             (" Player ", 42)
         };
 
-        var result = formatProperties?.Invoke(null, [properties]);
+        var dictionary = toPropertiesDictionary!.Invoke(null, [properties]) as IReadOnlyDictionary<string, object?>;
+        Assert.That(dictionary, Is.Not.Null, "ToPropertiesDictionary should return structured log properties.");
+
+        var result = GodotLogAppender.FormatProperties(dictionary);
 
         Assert.That(result, Is.EqualTo(" | Player=42"));
     }

GFramework.Godot/Logging/GodotLogAppender.cs

@@ -0,0 +1,211 @@
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using GFramework.Core.Abstractions.Logging;
+using Godot;
+
+namespace GFramework.Godot.Logging;
+
+/// <summary>
+///     Writes Core <see cref="LogEntry"/> instances to the Godot output APIs.
+/// </summary>
+/// <remarks>
+///     This appender is the Godot-specific edge of the Core logging pipeline. It keeps formatting, color selection, and
+///     Godot debugger routing in the host package while allowing consumers to compose Godot output with Core
+///     <see cref="ILogAppender"/> features such as <c>CompositeLogger</c>, filters, and async appenders. The appender
+///     does not own unmanaged resources; <see cref="Flush"/> and <see cref="Dispose"/> are therefore no-op lifecycle
+///     hooks that satisfy the shared appender contract.
+/// </remarks>
+public sealed class GodotLogAppender : ILogAppender
+{
+    private static readonly IReadOnlyDictionary<string, object?> EmptyProperties =
+        new Dictionary<string, object?>(StringComparer.Ordinal);
+
+    private readonly Func<GodotLoggerOptions> _optionsProvider;
+
+    /// <summary>
+    ///     Initializes a Godot appender with default Godot logger options.
+    /// </summary>
+    public GodotLogAppender()
+        : this(new GodotLoggerOptions())
+    {
+    }
+
+    /// <summary>
+    ///     Initializes a Godot appender with fixed Godot logger options.
+    /// </summary>
+    /// <param name="options">The formatting and routing options used for every appended entry.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="options"/> is <see langword="null"/>.</exception>
+    public GodotLogAppender(GodotLoggerOptions options)
+        : this(CreateFixedOptionsProvider(options))
+    {
+    }
+
+    /// <summary>
+    ///     Initializes a Godot appender with a dynamic options provider.
+    /// </summary>
+    /// <param name="optionsProvider">
+    ///     Provides the latest formatting and routing options for each append operation.
+    /// </param>
+    /// <remarks>
+    ///     The Godot logger provider uses this constructor so cached loggers observe hot-reloaded settings without
+    ///     being recreated. The provider must be fast and thread-safe because it is called on the logging path.
+    /// </remarks>
+    internal GodotLogAppender(Func<GodotLoggerOptions> optionsProvider)
+    {
+        _optionsProvider = optionsProvider ?? throw new ArgumentNullException(nameof(optionsProvider));
+    }
+
+    /// <summary>
+    ///     Appends one Core log entry to Godot's console and debugger output.
+    /// </summary>
+    /// <param name="entry">The Core log entry to render.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="entry"/> is <see langword="null"/>.</exception>
+    public void Append(LogEntry entry)
+    {
+        ArgumentNullException.ThrowIfNull(entry);
+
+        var options = _optionsProvider();
+        var rendered = Render(entry, options);
+
+        if (options.Mode == GodotLoggerMode.Debug)
+        {
+            WriteDebug(entry.Level, rendered);
+        }
+        else
+        {
+            GD.Print(rendered);
+        }
+
+        if (entry.Exception != null)
+        {
+            GD.PrintErr(entry.Exception.ToString());
+        }
+    }
+
+    /// <summary>
+    ///     Completes pending writes.
+    /// </summary>
+    /// <remarks>
+    ///     Godot output APIs are synchronous from this appender's point of view, so there is no buffered state to
+    ///     flush.
+    /// </remarks>
+    public void Flush()
+    {
+    }
+
+    /// <summary>
+    ///     Releases appender resources.
+    /// </summary>
+    /// <remarks>
+    ///     The appender does not own disposable Godot resources. This method exists to honor the Core appender
+    ///     lifecycle contract and to remain composable with factories that dispose appenders uniformly.
+    /// </remarks>
+    public void Dispose()
+    {
+    }
+
+    /// <summary>
+    ///     Formats structured properties for the <c>{properties}</c> template placeholder.
+    /// </summary>
+    /// <param name="properties">The already-merged property set from a Core <see cref="LogEntry"/>.</param>
+    /// <returns>
+    ///     A leading separator plus formatted properties, or an empty string when no valid properties exist.
+    /// </returns>
+    /// <remarks>
+    ///     Blank keys are ignored because they cannot produce useful structured output and can come from
+    ///     caller-provided tuples. Valid keys are trimmed at render time so the appender never mutates the original
+    ///     property dictionary.
+    /// </remarks>
+    internal static string FormatProperties(IReadOnlyDictionary<string, object?>? properties)
+    {
+        if (properties == null || properties.Count == 0)
+        {
+            return string.Empty;
+        }
+
+        var formattedProperties = properties
+            .Where(static pair => !string.IsNullOrWhiteSpace(pair.Key))
+            .Select(static pair => $"{pair.Key.Trim()}={FormatValue(pair.Value)}")
+            .ToArray();
+
+        return formattedProperties.Length == 0
+            ? string.Empty
+            : " | " + string.Join(", ", formattedProperties);
+    }
+
+    /// <summary>
+    ///     Renders a Core log entry without writing it to Godot.
+    /// </summary>
+    /// <param name="entry">The Core log entry to render.</param>
+    /// <returns>The line that would be sent to the selected Godot output API.</returns>
+    /// <remarks>
+    ///     Tests use this method to verify template and structured-property behavior without depending on Godot's
+    ///     static output APIs.
+    /// </remarks>
+    internal string Render(LogEntry entry)
+    {
+        ArgumentNullException.ThrowIfNull(entry);
+
+        return Render(entry, _optionsProvider());
+    }
+
+    private static Func<GodotLoggerOptions> CreateFixedOptionsProvider(GodotLoggerOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        return () => options;
+    }
+
+    private static string Render(LogEntry entry, GodotLoggerOptions options)
+    {
+        var templateText = options.Mode == GodotLoggerMode.Debug
+            ? options.DebugOutputTemplate
+            : options.ReleaseOutputTemplate;
+        var context = new GodotLogRenderContext(
+            entry.Timestamp,
+            entry.Level,
+            entry.LoggerName,
+            entry.Message,
+            options.GetColor(entry.Level),
+            FormatProperties(GetMergedProperties(entry)));
+
+        return GodotLogTemplate.Parse(templateText).Render(context);
+    }
+
+    private static IReadOnlyDictionary<string, object?> GetMergedProperties(LogEntry entry)
+    {
+        var allProperties = entry.GetAllProperties();
+        return allProperties.Count == 0 ? EmptyProperties : allProperties;
+    }
+
+    private static string FormatValue(object? value)
+    {
+        if (value == null)
+        {
+            return "null";
+        }
+
+        return value switch
+        {
+            IFormattable formattable => formattable.ToString(null, CultureInfo.InvariantCulture),
+            _ => value.ToString() ?? string.Empty
+        };
+    }
+
+    private static void WriteDebug(LogLevel level, string rendered)
+    {
+        GD.PrintRich(rendered);
+
+        switch (level)
+        {
+            case LogLevel.Fatal:
+            case LogLevel.Error:
+                GD.PushError(rendered);
+                break;
+            case LogLevel.Warning:
+                GD.PushWarning(rendered);
+                break;
+        }
+    }
+}

GFramework.Godot/Logging/GodotLogger.cs

@@ -1,19 +1,23 @@
 using System;
 using System.Collections.Generic;
-using System.Globalization;
-using System.Linq;
 using GFramework.Core.Abstractions.Logging;
 using GFramework.Core.Logging;
-using Godot;
 
 namespace GFramework.Godot.Logging;
 
 /// <summary>
 ///     Godot platform logger implementation.
 /// </summary>
+/// <remarks>
+///     This logger preserves the existing <see cref="ILogger"/> entry point while delegating output to
+///     <see cref="GodotLogAppender"/> so Godot rendering remains compatible with the Core appender pipeline.
+/// </remarks>
 public sealed class GodotLogger : AbstractLogger
 {
-    private readonly Func<GodotLoggerOptions> _optionsProvider;
+    private static readonly IReadOnlyDictionary<string, object?> EmptyProperties =
+        new Dictionary<string, object?>(StringComparer.Ordinal);
+
+    private readonly GodotLogAppender _appender;
 
     /// <summary>
     ///     Initializes a logger that preserves the historical fixed-format template.
@@ -45,11 +49,14 @@ public sealed class GodotLogger : AbstractLogger
     ///     Initializes the core logger with dynamic options and level providers.
     /// </summary>
     /// <param name="name">The resolved logger name used in rendered output.</param>
-    /// <param name="optionsProvider">The provider that supplies the latest rendering options for each write.</param>
+    /// <param name="optionsProvider">
+    ///     The provider that supplies the latest rendering options for each write.
+    /// </param>
     /// <param name="minLevelProvider">The provider that supplies the latest effective minimum level.</param>
     /// <remarks>
     ///     The Godot factory uses this constructor so cached logger instances can observe hot-reloaded settings without
-    ///     being recreated. The default public constructor supplies a fixed provider to avoid allocation on the log path.
+    ///     being recreated. The default public constructor supplies a fixed provider to avoid allocation on the log
+    ///     path.
     /// </remarks>
     internal GodotLogger(
         string name,
@@ -57,7 +64,8 @@ public sealed class GodotLogger : AbstractLogger
         Func<LogLevel> minLevelProvider)
         : base(name, minLevelProvider ?? throw new ArgumentNullException(nameof(minLevelProvider)))
     {
-        _optionsProvider = optionsProvider ?? throw new ArgumentNullException(nameof(optionsProvider));
+        _appender = new GodotLogAppender(
+            optionsProvider ?? throw new ArgumentNullException(nameof(optionsProvider)));
     }
 
     /// <summary>
@@ -74,6 +82,9 @@ public sealed class GodotLogger : AbstractLogger
     /// <summary>
     ///     Uses Godot-aware structured rendering instead of the base string concatenation fallback.
     /// </summary>
+    /// <param name="level">The log level.</param>
+    /// <param name="message">The message body before Godot template rendering.</param>
+    /// <param name="properties">Structured properties appended through the configured Godot template.</param>
     public override void Log(LogLevel level, string message, params (string Key, object? Value)[] properties)
     {
         if (!IsEnabled(level))
@@ -87,6 +98,10 @@ public sealed class GodotLogger : AbstractLogger
     /// <summary>
     ///     Uses Godot-aware structured rendering instead of the base string concatenation fallback.
     /// </summary>
+    /// <param name="level">The log level.</param>
+    /// <param name="message">The message body before Godot template rendering.</param>
+    /// <param name="exception">The optional exception written after the rendered message.</param>
+    /// <param name="properties">Structured properties appended through the configured Godot template.</param>
     public override void Log(
         LogLevel level,
         string message,
@@ -107,73 +122,39 @@ public sealed class GodotLogger : AbstractLogger
         Exception? exception,
         (string Key, object? Value)[]? properties)
     {
-        var options = _optionsProvider();
-        var templateText = options.Mode == GodotLoggerMode.Debug
-            ? options.DebugOutputTemplate
-            : options.ReleaseOutputTemplate;
-        var context = new GodotLogRenderContext(
+        var entry = new LogEntry(
             DateTime.UtcNow,
             level,
             Name(),
             message,
-            options.GetColor(level),
-            FormatProperties(properties));
-        var rendered = GodotLogTemplate.Parse(templateText).Render(context);
+            exception,
+            ToPropertiesDictionary(properties));
 
-        if (options.Mode == GodotLoggerMode.Debug)
-        {
-            WriteDebug(level, rendered);
-        }
-        else
-        {
-            GD.Print(rendered);
-        }
-
-        if (exception != null)
-        {
-            GD.PrintErr(exception.ToString());
-        }
+        _appender.Append(entry);
     }
 
-    private static string FormatProperties((string Key, object? Value)[]? properties)
+    private static IReadOnlyDictionary<string, object?> ToPropertiesDictionary(
+        (string Key, object? Value)[]? properties)
     {
-        var merged = MergeProperties(properties);
-        if (merged.Count == 0)
-        {
-            return string.Empty;
-        }
-
-        return " | " + string.Join(", ", merged.Select(static pair => $"{pair.Key}={FormatValue(pair.Value)}"));
-    }
-
-    private static IReadOnlyDictionary<string, object?> MergeProperties((string Key, object? Value)[]? properties)
-    {
-        var contextProperties = LogContext.Current;
-        if ((properties == null || properties.Length == 0) && contextProperties.Count == 0)
+        if (properties == null || properties.Length == 0)
         {
             return EmptyProperties;
         }
 
-        var merged = new Dictionary<string, object?>(contextProperties, StringComparer.Ordinal);
-        if (properties != null)
+        var result = new Dictionary<string, object?>(StringComparer.Ordinal);
+        foreach (var property in properties)
         {
-            foreach (var property in properties)
+            if (string.IsNullOrWhiteSpace(property.Key))
             {
-                if (string.IsNullOrWhiteSpace(property.Key))
-                {
-                    continue;
-                }
-
-                merged[property.Key.Trim()] = property.Value;
+                continue;
             }
+
+            result[property.Key.Trim()] = property.Value;
         }
 
-        return merged;
+        return result.Count == 0 ? EmptyProperties : result;
     }
 
-    private static readonly IReadOnlyDictionary<string, object?> EmptyProperties =
-        new Dictionary<string, object?>(StringComparer.Ordinal);
-
     private static Func<GodotLoggerOptions> CreateFixedOptionsProvider(LogLevel minLevel)
     {
         var options = GodotLoggerOptions.ForMinimumLevel(minLevel);
@@ -191,34 +172,4 @@ public sealed class GodotLogger : AbstractLogger
         ArgumentNullException.ThrowIfNull(options);
         return () => options.GetEffectiveMinLevel();
     }
-
-    private static string FormatValue(object? value)
-    {
-        if (value == null)
-        {
-            return "null";
-        }
-
-        return value switch
-        {
-            IFormattable formattable => formattable.ToString(null, CultureInfo.InvariantCulture),
-            _ => value.ToString() ?? string.Empty
-        };
-    }
-
-    private static void WriteDebug(LogLevel level, string rendered)
-    {
-        GD.PrintRich(rendered);
-
-        switch (level)
-        {
-            case LogLevel.Fatal:
-            case LogLevel.Error:
-                GD.PushError(rendered);
-                break;
-            case LogLevel.Warning:
-                GD.PushWarning(rendered);
-                break;
-        }
-    }
 }

GFramework.Godot/README.md

@@ -72,7 +72,7 @@ Scene / UI、配置、存储、设置、日志与协程能力接到 `Node`、`Sc
 
 - 节点扩展与 `Signal(...)` fluent API
 - `GodotTimeSource` 与协程时间分段
-- Godot 日志 provider
+- Godot 日志 provider 与 `GodotLogAppender`
 - 暂停处理、节点池与富文本效果支持
 
 这些目录都是“宿主适配层”，不是新的 gameplay 抽象层。

ai-plan/public/README.md

@@ -38,10 +38,6 @@ help the current worktree land on the right recovery documents without scanning
   - Purpose: continue the data repository persistence hardening plus the settings / serialization follow-up backlog.
   - Tracking: `ai-plan/public/data-repository-persistence/todos/data-repository-persistence-tracking.md`
   - Trace: `ai-plan/public/data-repository-persistence/traces/data-repository-persistence-trace.md`
-- `godot-logging-compliance-polish`
-  - Purpose: continue Godot logging host integration, configuration reload, structured-output polish, and follow-up work without forking the Core logging model.
-  - Tracking: `ai-plan/public/godot-logging-compliance-polish/todos/godot-logging-compliance-polish-tracking.md`
-  - Trace: `ai-plan/public/godot-logging-compliance-polish/traces/godot-logging-compliance-polish-trace.md`
 - `semantic-release-versioning`
   - 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`
@@ -63,23 +59,9 @@ help the current worktree land on the right recovery documents without scanning
 - Branch: `feat/data-repository-persistence`
   - Worktree hint: `GFramework-data-repository-persistence`
   - Priority 1: `data-repository-persistence`
-- Branch: `feat/godot-logging-compliance-polish`
-  - Worktree hint: `GFramework`
-  - Priority 1: `godot-logging-compliance-polish`
 - Branch: `feat/semantic-release-versioning`
   - Worktree hint: `GFramework`
   - Priority 1: `semantic-release-versioning`
 - Branch: `docs/sdk-update-documentation`
   - Worktree hint: `GFramework-update-documentation`
   - Priority 1: `documentation-full-coverage-governance`
-## Archived Topics
-
-- `analyzer-warning-reduction`
-  - Archive root: `ai-plan/public/archive/analyzer-warning-reduction/`
-  - Note: 长期 warning-reduction 分支已收尾；PR #301 的最终 review follow-up 已本地闭环，后续仅作为历史恢复材料保留。
-- `cqrs-cache-docs-hardening`
-  - Archive root: `ai-plan/public/archive/cqrs-cache-docs-hardening/`
-  - Note: archived topics stay outside the default `boot` context until a user explicitly requests historical review.
-- `documentation-governance-and-refresh`
-  - Archive root: `ai-plan/public/archive/documentation-governance-and-refresh/`
-  - Note: PR #268 已合并；文档治理与 Godot 栏目刷新阶段已完成，后续仅作为历史恢复材料保留。

ai-plan/public/archive/godot-logging-compliance-polish/todos/godot-logging-compliance-polish-tracking.md

@@ -5,17 +5,17 @@
 继续把 `GFramework.Godot.Logging` 从“基础可用的 Godot 输出适配”收敛成“对齐 `GodotLogger` 优点、但保持
 GFramework 自身日志抽象不分叉”的稳定宿主层，并为后续 Godot / Core 日志统一留下清晰恢复点。
 
-## 当前恢复点
+## 完成状态
 
 - 恢复点编号：`GODOT-LOGGING-COMPLIANCE-POLISH-RP-003`
-- 当前阶段：`PR review follow-up`
-- 当前焦点：
+- 当前阶段：`已完成并归档`
+- 完成结论：
   - 已补齐 `GodotLog` 静态入口、延迟 logger 解析、配置自动发现与热重载
   - 已让 `GodotLoggerFactoryProvider` 对已缓存 logger 生效动态配置，而不是只在新建 logger 时读快照
   - 已让 `GodotLogger` 支持 `{properties}` 占位符，并把 `IStructuredLogger` / `LogContext` 属性落到 Godot 输出
   - 已兼容 `GodotLogger` 风格配置值，如 `Information` / `Critical`
   - 已处理 PR #314 最新 AI review 中仍适用的 XML docs、热路径分配、结构化属性兜底、文档示例和 tracking 精简问题
-  - 下一轮优先刷新 PR review / CI 反馈，避免继续扩大 Godot logging API 面
+  - PR #314 已合并到 `origin/main`，当前主题从默认 boot 路径移入归档
 
 ## 当前状态摘要
 
@@ -31,7 +31,8 @@ GFramework 自身日志抽象不分叉”的稳定宿主层，并为后续 Godot
 
 ## 当前活跃事实
 
-- 当前主题由分支 `feat/godot-logging-compliance-polish` 驱动，并已在 `ai-plan/public/README.md` 建立映射
+- 本主题归档前由分支 `feat/godot-logging-compliance-polish` 驱动，PR #314 合并后已从
+  `ai-plan/public/README.md` 的 active topic 映射移除
 - `ai-libs/GodotLogger` 的 MIT 许可证已复制到 `third-party-licenses/GodotLogger/LICENSE`
 - `GodotLog` 当前的配置发现顺序为：
   - `GODOT_LOGGER_CONFIG`
@@ -53,12 +54,12 @@ GFramework 自身日志抽象不分叉”的稳定宿主层，并为后续 Godot
 - PR #314 最新 follow-up 中，`DeferredLogger` 格式化重载现在委托给 inner logger，`GodotLogger` 默认 options
   provider 已改为构造时缓存，结构化属性会跳过空白 key 并使用 trimmed key
 
-## 当前风险
+## 收尾风险
 
 - 双入口生命周期风险：如果同一宿主同时混用 `LoggerFactoryResolver.Provider` 与 `GodotLog`，需要明确谁是最终默认 provider
   - 缓解措施：当前文档与实现都保留 `GodotLog.UseAsDefaultProvider()`，并继续把 `ArchitectureConfiguration` 方式写成默认推荐路径
 - Core / Godot 管线分离风险：Godot 侧虽然已有热重载与配置发现，但还没有变成 Core 可组合 appender
-  - 缓解措施：下一轮只评估“Godot sink / appender 化”，不再继续扩张独立的 Godot logging 面
+  - 缓解措施：若后续重启本方向，应新建独立 topic 评估“Godot sink / appender 化”，不要在已归档主题继续扩张独立的 Godot logging 面
 - 配置热重载的宿主差异风险：Godot 编辑器、导出包和测试宿主的文件系统语义不完全一致
   - 缓解措施：active 入口先锁定 discovery / reload 语义，后续若遇到平台差异，再用定向回归和文档补充收口
 - `GodotLog.ConfigurationPath` 的“不会 materialize”语义没有加入自动化测试
@@ -80,11 +81,14 @@ GFramework 自身日志抽象不分叉”的稳定宿主层，并为后续 Godot
 - `dotnet format GFramework.Godot.Tests/GFramework.Godot.Tests.csproj --verify-no-changes --no-restore --include ...`
   - 结果：通过
   - 备注：include 范围为本轮修改的 C# 文件；全项目 format 仍命中既有行尾 / 编码问题，详见 trace
+- `dotnet build GFramework.sln -c Release`
+  - 结果：通过，`0 warning / 0 error`
+  - 备注：2026-05-03 在归档维护分支补跑仓库级 Release build，验证归档改动不会影响解决方案构建
 - 历史验证明细已保留在 [执行 trace](../traces/godot-logging-compliance-polish-trace.md) 的 `RP-001 验证` 与
   `RP-002 验证` 小节，active tracking 入口只保留当前恢复点相关结果
 
-## 下一步
+## 归档说明
 
-1. 提交 RP-003 review follow-up 改动
-2. 刷新 PR review / CI 状态，确认最新 head 上 CodeRabbit 与 Greptile 线程是否关闭或变为 stale
-3. 若 CI 仍报 MegaLinter `dotnet-format` restore 失败，优先复核 Actions restore 环境，而不是继续改本地格式
+1. 本主题已随 PR #314 合并到 `origin/main`
+2. 默认 boot 索引不再指向本主题
+3. 后续若继续做 Godot logging 与 Core appender / sink 的统一设计，应建立新的 active topic

ai-plan/public/archive/godot-logging-compliance-polish/traces/godot-logging-compliance-polish-trace.md

@@ -117,3 +117,24 @@
 1. 提交 RP-003 review follow-up 改动
 2. 刷新 PR review，确认 CodeRabbit / Greptile 线程是否关闭或 stale
 3. 若 CI 仍只有 MegaLinter `dotnet-format` restore 失败，继续定位 Actions restore 环境而不是扩大本地格式清理范围
+
+### 阶段：主题归档（RP-004）
+
+- PR #314 已合并，当前分支 head 与 `origin/main` 同为 merge commit `918a61f3`
+- 旧 upstream branch `origin/feat/godot-logging-compliance-polish` 已不存在
+- 当前 batch stop condition 使用 `origin/main` 作为 baseline；归档前分支累计 diff 为 `0` 个文件
+- 接受的收尾动作：
+  - 将 `godot-logging-compliance-polish` 从默认 boot active topic 中移除
+  - 将主题恢复文档移动到 `ai-plan/public/archive/godot-logging-compliance-polish/`
+  - 在 public index 的 archived topics 中保留主题位置和合并结论
+
+### RP-004 验证
+
+- `dotnet build GFramework.sln -c Release`
+  - 结果：通过，`0 warning / 0 error`
+  - 备注：归档维护只触及 `ai-plan/public/**`，本次 build 用于满足仓库完成标准并确认解决方案仍可构建
+
+### RP-004 下一步
+
+1. 若继续推进 Godot logging 与 Core 的统一输出管线，建立新的 active topic
+2. 当前归档维护已完成；后续只需提交并发布归档分支

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

@@ -0,0 +1,76 @@
+# Godot Logging Core Sink 跟踪
+
+## 目标
+
+在 `GFramework.Godot.Logging` 已完成宿主便利层收口后，评估并推进 Godot 输出与 `GFramework.Core` 日志扩展点的统一。
+本主题优先判断是否应把 Godot 输出沉淀为 Core 可组合的 appender / sink，而不是继续扩张 Godot-only logging 管线。
+
+## 完成状态
+
+- 恢复点编号：`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 移除
+
+## 已知输入
+
+- `godot-logging-compliance-polish` 已归档，PR #314 已合并到 `origin/main`
+- 归档主题确认：
+  - `GFramework.Core` 仍是主日志框架
+  - `GFramework.Godot.Logging` 已补齐 `GodotLog`、延迟 logger、配置发现、热重载和结构化属性渲染
+  - 下一阶段应新建 topic 评估 Godot sink / appender 化，而不是继续在归档主题内扩张
+- `ai-libs/GodotLogger` 继续作为只读外部参考；本主题不引入 `Microsoft.Extensions.Logging` provider / builder 生态
+
+## 待办
+
+1. 已完成：盘点 `GFramework.Core` 日志扩展点与 Godot 侧 logger/provider 的实际耦合点
+2. 已完成：确认现有 Core `ILogAppender` 足够承载 Godot 输出，无需新增第二套 sink API
+3. 已完成：保留 `GodotLog` / `GodotLoggerFactoryProvider` 入口，并让 `GodotLogger` 底层走 `GodotLogAppender`
+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 显式组合
+8. 已完成：归档 `godot-logging-core-sink` 主题，默认 boot 不再加载本主题
+
+## 验证
+
+- `dotnet build GFramework.sln -c Release`
+  - 结果：通过，`0 warning / 0 error`
+  - 备注：2026-05-03 在创建本 active topic 前已验证归档收尾分支；后续实现改动需要按受影响项目重新验证
+- `dotnet test GFramework.Godot.Tests -c Release`
+  - 结果：通过，`75 passed / 0 failed / 0 skipped`
+  - 备注：覆盖 `GodotLogAppender` 渲染、动态 options provider、既有 Godot logging tests
+- `dotnet build GFramework.Godot -c Release`
+  - 结果：通过，`0 warning / 0 error`
+  - 备注：验证受影响运行时项目
+- `dotnet format GFramework.Godot --verify-no-changes --no-restore --include GFramework.Godot/Logging/GodotLogger.cs`
+  - 结果：通过
+- `dotnet format GFramework.Godot.Tests --verify-no-changes --no-restore --include GFramework.Godot.Tests/Logging/GodotLogAppenderTests.cs GFramework.Godot.Tests/Logging/GodotLoggerSettingsLoaderTests.cs`
+  - 结果：通过
+- `dotnet test GFramework.Godot.Tests -c Release`
+  - 结果：通过，`75 passed / 0 failed / 0 skipped`
+  - 备注：2026-05-03 最新 PR review outside-diff 复查后重新验证
+- `dotnet format GFramework.Godot.Tests --verify-no-changes --no-restore --include GFramework.Godot.Tests/Logging/GodotLoggerSettingsLoaderTests.cs`
+  - 结果：通过
+  - 备注：覆盖最新改动的测试文件
+- `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 #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

@@ -0,0 +1,143 @@
+# Godot Logging Core Sink Trace
+
+## 2026-05-03
+
+### RP-001 启动
+
+- 新建 active topic：`godot-logging-core-sink`
+- 当前分支：`feat/godot-logging-core-sink`
+- 启动背景：
+  - `godot-logging-compliance-polish` 已随 PR #314 合并并归档
+  - 用户明确要求归档收尾不要作为独立分支推进，而是跟下一 active topic 一起提交
+  - 本分支因此同时包含归档索引收口和新 topic 启动入口
+
+### 初始边界
+
+- 本主题要评估 Godot 输出是否应进入 Core appender / sink 模型
+- 不把 `Microsoft.Extensions.Logging` 生态原样搬入 GFramework
+- 不新增第二套业务日志 API；`GodotLog` 应保持为 Godot 宿主便利入口
+- 不在已归档的 `godot-logging-compliance-polish` topic 中继续扩张新需求
+
+### RP-001 验证
+
+- `dotnet build GFramework.sln -c Release`
+  - 结果：通过，`0 warning / 0 error`
+  - 备注：本次 build 在创建 active topic 前执行，用于验证归档维护对解决方案无影响；实现阶段需要重新跑受影响项目验证
+
+### RP-001 下一步
+
+1. 只读盘点 Core logging 抽象与 Godot logger/provider 的耦合点
+2. 记录候选设计，明确哪些能力进入 Core，哪些保留在 Godot 宿主层
+3. 确认方案后进入实现与文档更新
+
+### RP-002 Godot Appender 最小实现
+
+- 盘点结论：
+  - Core 已有 `ILogAppender`、`LogEntry`、`CompositeLogger`、filter、formatter 与 async appender
+  - Godot 侧主要耦合点是 `GodotLogger` 直接持有模板渲染和 `GD.*` 输出逻辑
+  - 不需要先新增 Core sink 抽象；把 Godot 输出沉淀为 Godot 包内的 `ILogAppender` 已能复用 Core 管线
+- 已实施：
+  - 新增 `GFramework.Godot.Logging.GodotLogAppender`
+  - `GodotLogger` 保留原有 public API，并把输出委托给 `GodotLogAppender`
+  - 新增 `GFramework.Godot.Tests/Logging/GodotLogAppenderTests.cs`
+  - 更新 `GFramework.Godot/README.md`、`docs/zh-CN/core/logging.md`、`docs/zh-CN/godot/index.md`、
+    `docs/zh-CN/godot/logging.md`
+- 采用的兼容边界：
+  - `GodotLog`、`GodotLoggerFactory`、`GodotLoggerFactoryProvider` 不改用户调用方式
+  - Godot 输出可作为 Core appender 被自定义 factory / `CompositeLogger` 组合
+  - 文件、JSON、namespace filter、async 等仍由 Core logging 组件负责，Godot 包只提供宿主控制台落点
+
+### RP-002 验证
+
+- `dotnet test GFramework.Godot.Tests -c Release`
+  - 结果：通过，`75 passed / 0 failed / 0 skipped`
+- `dotnet build GFramework.Godot -c Release`
+  - 结果：通过，`0 warning / 0 error`
+
+### RP-002 下一步
+
+1. 提交当前 appender 实现与文档更新
+2. 若继续推进本主题，优先补充组合示例或归档 topic，不新增第二套日志 API
+
+### RP-003 PR Review Follow-up
+
+- 使用 `$gframework-pr-review` 抓取 PR #315 最新 review payload：
+  - CodeRabbit：3 个 open thread，分别指向 appender test 顺序依赖、默认 boot index 包含 archived topic、trace 重复 heading
+  - Greptile：1 个 open thread，指出 `GodotLogger.FormatProperties` 为 dead private wrapper
+  - Gemini Code Assist：无 open thread
+  - GitHub Test Reporter：`2264 passed / 0 failed`
+  - MegaLinter：`dotnet-format` 报 restore failure；本地进一步验证时发现 solution-wide format 还有既有 repo-wide 诊断
+- 已实施：
+  - `GodotLogAppenderTests` 改为验证固定前缀与结构化属性集合内容，不再依赖 `Dictionary` 枚举顺序
+  - 移除 `GodotLogger.FormatProperties` private wrapper，并把既有结构化属性测试改为验证生产路径使用的 `ToPropertiesDictionary` 与 `GodotLogAppender.FormatProperties`
+  - 从 `ai-plan/public/README.md` 移除 archived topics 区块，默认 boot index 只保留 active topic 与 worktree map
+  - 将 trace 中重复的 `### 验证` / `### 下一步` 改为 `RP-001` 与 `RP-002` 前缀，避免 MD024 anchor 冲突
+
+### RP-003 验证
+
+- `dotnet test GFramework.Godot.Tests -c Release`
+  - 结果：通过，`75 passed / 0 failed / 0 skipped`
+- `dotnet build GFramework.Godot -c Release`
+  - 结果：通过，`0 warning / 0 error`
+- `dotnet format GFramework.Godot --verify-no-changes --no-restore --include GFramework.Godot/Logging/GodotLogger.cs`
+  - 结果：通过
+- `dotnet format GFramework.Godot.Tests --verify-no-changes --no-restore --include GFramework.Godot.Tests/Logging/GodotLogAppenderTests.cs GFramework.Godot.Tests/Logging/GodotLoggerSettingsLoaderTests.cs`
+  - 结果：通过
+- `dotnet format GFramework.sln --verify-no-changes --no-restore`
+  - 结果：失败
+  - 备注：失败为仓库既有的跨项目 whitespace、final newline 与 charset 诊断；本轮改动文件已通过 scoped format 验证
+
+### RP-003 下一步
+
+1. 提交 PR review follow-up
+2. 等待 PR #315 复查，确认 CodeRabbit / Greptile open threads 是否关闭
+
+### RP-004 PR Review Outside-Diff 复查
+
+- 使用 `$gframework-pr-review` 重新抓取 PR #315 最新 review payload：
+  - CodeRabbit：无 open thread，但 latest review body 仍有 1 条 outside-diff 反馈
+  - Greptile：无 open thread
+  - Gemini Code Assist：无 open thread
+  - GitHub Test Reporter：最新 run 显示 `2264 passed / 0 failed`
+  - MegaLinter：仍为 `dotnet-format` restore failure，未提供具体源文件格式诊断
+- 已实施：
+  - `GodotLoggerSettingsLoaderTests.StructuredProperties_Should_Skip_Blank_Keys_And_Trim_Valid_Keys` 在调用反射目标前显式断言 `ToPropertiesDictionary` 存在
+  - 同一测试在交给 `GodotLogAppender.FormatProperties` 前显式断言反射返回值类型符合预期
+
+### RP-004 验证
+
+- `dotnet test GFramework.Godot.Tests -c Release`
+  - 结果：通过，`75 passed / 0 failed / 0 skipped`
+- `dotnet format GFramework.Godot.Tests --verify-no-changes --no-restore --include GFramework.Godot.Tests/Logging/GodotLoggerSettingsLoaderTests.cs`
+  - 结果：通过
+
+### RP-004 下一步
+
+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

@@ -79,6 +79,68 @@ using (LogContext.Push("RequestId", requestId))
 `LoggingConfigurationLoader` 读取 `LoggingConfiguration`，再把自定义 `ILoggerFactoryProvider` 挂到
 `ArchitectureConfiguration.LoggerProperties.LoggerFactoryProvider` 或 `LoggerFactoryResolver.Provider`。
 
+宿主包也可以提供自己的 appender。Godot 项目如果需要把 Core 日志管线输出到 Godot 控制台，可以引用
+`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`：
@@ -87,5 +149,6 @@ using (LogContext.Push("RequestId", requestId))
 - 需要按 namespace / level 做过滤
 - 需要 JSON 格式日志
 - 需要组合多个 appender
+- 需要把输出落到 Godot、Unity 或其他宿主控制台
 
 这时更合理的做法是保留 `ILogger` 调用面不变，只替换 provider / factory / formatter / appender 组合。

docs/zh-CN/godot/index.md

@@ -16,7 +16,7 @@ description: 以当前 GFramework.Godot 源码、测试与 CoreGrid 接线为准
 - 节点运行时辅助：`WaitUntilReadyAsync()`、`AddChildXAsync()`、`QueueFreeX()`、`UnRegisterWhenNodeExitTree(...)`
 - Godot 风格的 Scene / UI 工厂与 registry：`GodotSceneFactory`、`GodotUiFactory`
 - Godot 特化的存储、设置与配置加载：`GodotFileStorage`、`GodotAudioSettings`、`GodotYamlConfigLoader`
-- 少量面向运行时交互的扩展：`Signal(...)` fluent API、暂停处理、富文本效果、协程时间源
+- 少量面向运行时交互的扩展：`Signal(...)` fluent API、`GodotLogAppender`、暂停处理、富文本效果、协程时间源
 
 它不是 `[GetNode]`、`[BindNodeSignal]`、`AutoLoads`、`InputActions` 的来源。这些能力属于
 `GFramework.Godot.SourceGenerators`。

docs/zh-CN/godot/logging.md

@@ -9,6 +9,7 @@ description: 以当前 GFramework.Godot.Logging 源码与 CoreGrid 接线为准
 除了把日志写到 Godot 控制台，它现在还补上了 Godot 宿主常见的接入便利层：
 
 - `GodotLog` 静态入口
+- `GodotLogAppender`，用于接入 Core appender 管线
 - 配置文件自动发现
 - 运行期配置热重载
 - 延迟 logger 解析，适合 `static readonly` 字段
@@ -20,7 +21,9 @@ description: 以当前 GFramework.Godot.Logging 源码与 CoreGrid 接线为准
 
 ### `GodotLogger`
 
-`GodotLogger` 继承自 `AbstractLogger`，负责把日志写到 Godot 的输出 API：
+`GodotLogger` 继承自 `AbstractLogger`，保留原有 `ILogger` 使用面。它现在把实际输出委托给
+`GodotLogAppender`，所以 `GodotLoggerFactoryProvider` 继续可用，同时 Godot 输出也能作为 Core appender 管线的一个
+可组合目标：
 
 ```csharp
 public sealed class GodotLogger(
@@ -32,10 +35,27 @@ public sealed class GodotLogger(
 当前实现里的几个关键语义：
 
 - 时间戳使用 `DateTime.UtcNow`
-- 输出前缀格式是 `[yyyy-MM-dd HH:mm:ss.fff] LEVEL [LoggerName]`
-- `exception` 不会被单独结构化处理，而是直接追加到消息后面
-- `Trace` / `Debug` 走 `GD.PrintRich(...)`
-- `Info` / `Warning` / `Error` / `Fatal` 分别走 Godot 自身的普通、警告和错误输出通道
+- 模板、级别、颜色仍由 `GodotLoggerOptions` 或配置文件控制
+- 结构化属性来自 `IStructuredLogger` 参数和 `LogContext`
+- `exception` 会在渲染后的主消息之后写入 Godot 错误输出
+
+### `GodotLogAppender`
+
+`GodotLogAppender` 实现 Core 的 `ILogAppender`：
+
+```csharp
+public sealed class GodotLogAppender : ILogAppender
+{
+    public GodotLogAppender();
+    public GodotLogAppender(GodotLoggerOptions options);
+    public void Append(LogEntry entry);
+    public void Flush();
+}
+```
+
+它适合在已经使用 `CompositeLogger`、`AsyncLogAppender`、filter 或自定义 factory 的项目里，把 Godot 控制台输出作为
+其中一个落点，而不是为 Godot 重新定义一套业务日志 API。`Flush()` 和 `Dispose()` 没有额外副作用，因为 Godot 输出 API
+对这个 appender 来说没有持有的缓冲区或外部资源。
 
 ### `GodotLoggerFactory`
 
@@ -109,7 +129,7 @@ var logger = GodotLog.CreateLogger<Main>();
       "Mode": "Debug",
       "DebugMinLevel": "Debug",
       "ReleaseMinLevel": "Info",
-      "DebugOutputTemplate": "[{timestamp:HH:mm:ss.fff}] [color={color}][{level:u3}][/color] [{category:l16}] {message}{properties}",
+      "DebugOutputTemplate": "[{timestamp:HH:mm:ss.fff}] [color={color}]{level:u3}[/color] {message}{properties}",
       "ReleaseOutputTemplate": "[{timestamp:HH:mm:ss.fff}] [{level:u3}] [{category:l16}] {message}{properties}",
       "Colors": {
         "Info": "white",
@@ -196,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;
@@ -214,16 +295,16 @@ RegisterHandler(new LoggingTransitionHandler());
 
 ## Godot 控制台输出语义
 
-当前 `GodotLogger.Write(...)` 的级别映射如下：
+当前 `GodotLogAppender.Append(...)` 的级别映射如下：
 
 | 日志级别 | Godot 输出 API | 当前行为 |
 | --- | --- | --- |
-| `Trace` | `GD.PrintRich(...)` | 使用灰色富文本输出 |
-| `Debug` | `GD.PrintRich(...)` | 使用青色富文本输出 |
-| `Info` | `GD.Print(...)` | 普通控制台输出 |
-| `Warning` | `GD.PushWarning(...)` | 进入 Godot 警告通道 |
-| `Error` | `GD.PrintErr(...)` | 输出到错误流 |
-| `Fatal` | `GD.PushError(...)` | 进入 Godot 错误通道 |
+| `Trace` | `GD.PrintRich(...)` 或 `GD.Print(...)` | Debug 模式使用富文本，Release 模式使用普通输出 |
+| `Debug` | `GD.PrintRich(...)` 或 `GD.Print(...)` | Debug 模式使用富文本，Release 模式使用普通输出 |
+| `Info` | `GD.PrintRich(...)` 或 `GD.Print(...)` | Debug 模式使用富文本，Release 模式使用普通输出 |
+| `Warning` | `GD.PrintRich(...)` + `GD.PushWarning(...)` 或 `GD.Print(...)` | Debug 模式同时进入 Godot 警告通道 |
+| `Error` | `GD.PrintRich(...)` + `GD.PushError(...)` 或 `GD.Print(...)` | Debug 模式同时进入 Godot 错误通道 |
+| `Fatal` | `GD.PrintRich(...)` + `GD.PushError(...)` 或 `GD.Print(...)` | Debug 模式同时进入 Godot 错误通道 |
 
 结构化属性如果通过 `IStructuredLogger` 或 `LogContext` 传入，也会追加到模板里的 `{properties}` 占位符。
 
@@ -259,8 +340,8 @@ System.IO.IOException: ...
 
 - 当前推荐接法仍然是把 `GodotLoggerFactoryProvider` 放进 `ArchitectureConfiguration.LoggerProperties`；如果项目是纯
   Godot 宿主，也可以在入口直接调用 `GodotLog.UseAsDefaultProvider()`
-- `GFramework.Godot.Logging` 只解决 Godot 控制台输出，不提供文件落盘、JSON formatter、异步 appender 或按 namespace
-  的复杂过滤
+- `GFramework.Godot.Logging` 只提供 Godot 控制台 appender；文件落盘、JSON formatter、异步 appender 或按 namespace
+  的复杂过滤继续使用 Core 日志组件组合
 - `GodotLogger` 只改变输出方式，不改变 `ILogger` 接口本身；业务代码不需要切换到 Godot 专用日志 API
 - `[Log]`、`[ContextAware]` 这类字段注入能力不属于 `GFramework.Godot.Logging`
 - Scene / UI 的 `LoggingTransitionHandler` 位于 `GFramework.Game`，Godot 侧只是通过 provider 让它们输出到 Godot 控制台