From 40cce565e6537f894f57d44b19f8a0fd7bb0b5d4 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sun, 3 May 2026 10:51:16 +0800 Subject: [PATCH] =?UTF-8?q?docs(ai-plan):=20=E5=90=AF=E5=8A=A8=20Godot=20l?= =?UTF-8?q?ogging=20Core=20sink=20=E4=B8=BB=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 归档 Godot logging 合规收尾主题并保留验证结果 - 新增 Godot logging Core sink active topic 恢复入口 - 更新 public boot 索引和当前分支映射 --- ai-plan/public/README.md | 19 +++++--- ...odot-logging-compliance-polish-tracking.md | 26 ++++++----- .../godot-logging-compliance-polish-trace.md | 21 +++++++++ .../todos/godot-logging-core-sink-tracking.md | 43 +++++++++++++++++++ .../traces/godot-logging-core-sink-trace.md | 31 +++++++++++++ 5 files changed, 122 insertions(+), 18 deletions(-) rename ai-plan/public/{ => archive}/godot-logging-compliance-polish/todos/godot-logging-compliance-polish-tracking.md (85%) rename ai-plan/public/{ => archive}/godot-logging-compliance-polish/traces/godot-logging-compliance-polish-trace.md (87%) create mode 100644 ai-plan/public/godot-logging-core-sink/todos/godot-logging-core-sink-tracking.md create mode 100644 ai-plan/public/godot-logging-core-sink/traces/godot-logging-core-sink-trace.md diff --git a/ai-plan/public/README.md b/ai-plan/public/README.md index 447d2d23..98876db1 100644 --- a/ai-plan/public/README.md +++ b/ai-plan/public/README.md @@ -38,14 +38,15 @@ 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` - 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 @@ -63,15 +64,16 @@ 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: `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` + ## Archived Topics - `analyzer-warning-reduction` @@ -83,3 +85,6 @@ help the current worktree land on the right recovery documents without scanning - `documentation-governance-and-refresh` - Archive root: `ai-plan/public/archive/documentation-governance-and-refresh/` - Note: PR #268 已合并；文档治理与 Godot 栏目刷新阶段已完成，后续仅作为历史恢复材料保留。 +- `godot-logging-compliance-polish` + - Archive root: `ai-plan/public/archive/godot-logging-compliance-polish/` + - Note: PR #314 已合并到 `origin/main`；Godot logging 宿主集成、热重载、结构化输出和 review follow-up 已收尾，后续 Core appender / sink 统一评估应新建 active topic。 diff --git a/ai-plan/public/godot-logging-compliance-polish/todos/godot-logging-compliance-polish-tracking.md b/ai-plan/public/archive/godot-logging-compliance-polish/todos/godot-logging-compliance-polish-tracking.md similarity index 85% rename from ai-plan/public/godot-logging-compliance-polish/todos/godot-logging-compliance-polish-tracking.md rename to ai-plan/public/archive/godot-logging-compliance-polish/todos/godot-logging-compliance-polish-tracking.md index b2b18dcd..506d0425 100644 --- a/ai-plan/public/godot-logging-compliance-polish/todos/godot-logging-compliance-polish-tracking.md +++ b/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 diff --git a/ai-plan/public/godot-logging-compliance-polish/traces/godot-logging-compliance-polish-trace.md b/ai-plan/public/archive/godot-logging-compliance-polish/traces/godot-logging-compliance-polish-trace.md similarity index 87% rename from ai-plan/public/godot-logging-compliance-polish/traces/godot-logging-compliance-polish-trace.md rename to ai-plan/public/archive/godot-logging-compliance-polish/traces/godot-logging-compliance-polish-trace.md index 915585c8..9823b69e 100644 --- a/ai-plan/public/godot-logging-compliance-polish/traces/godot-logging-compliance-polish-trace.md +++ b/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. 当前归档维护已完成；后续只需提交并发布归档分支 diff --git a/ai-plan/public/godot-logging-core-sink/todos/godot-logging-core-sink-tracking.md b/ai-plan/public/godot-logging-core-sink/todos/godot-logging-core-sink-tracking.md new file mode 100644 index 00000000..e1ac8d93 --- /dev/null +++ b/ai-plan/public/godot-logging-core-sink/todos/godot-logging-core-sink-tracking.md @@ -0,0 +1,43 @@ +# Godot Logging Core Sink 跟踪 + +## 目标 + +在 `GFramework.Godot.Logging` 已完成宿主便利层收口后，评估并推进 Godot 输出与 `GFramework.Core` 日志扩展点的统一。 +本主题优先判断是否应把 Godot 输出沉淀为 Core 可组合的 appender / sink，而不是继续扩张 Godot-only logging 管线。 + +## 当前恢复点 + +- 恢复点编号：`GODOT-LOGGING-CORE-SINK-RP-001` +- 当前阶段：`启动与边界确认` +- 当前焦点： + - 复查 `GFramework.Core` 当前日志抽象、provider、appender / sink 能力与扩展边界 + - 对照已归档的 `godot-logging-compliance-polish` 结论，确认哪些能力应迁移为 Core 通用扩展，哪些能力应保留在 Godot 宿主层 + - 形成最小实现路径，避免同时引入第二套日志 API 或破坏现有 `GodotLog` 入口 + +## 已知输入 + +- `godot-logging-compliance-polish` 已归档，PR #314 已合并到 `origin/main` +- 归档主题确认： + - `GFramework.Core` 仍是主日志框架 + - `GFramework.Godot.Logging` 已补齐 `GodotLog`、延迟 logger、配置发现、热重载和结构化属性渲染 + - 下一阶段应新建 topic 评估 Godot sink / appender 化，而不是继续在归档主题内扩张 +- 当前分支同时承载归档收尾与本 active topic 启动，避免为纯归档维护单独开 PR + +## 待办 + +1. 盘点 `GFramework.Core` 日志扩展点与 Godot 侧 logger/provider 的实际耦合点 +2. 判断 Core appender / sink 抽象是否已足够承载 Godot 输出，还是需要先补齐抽象层能力 +3. 制定兼容路径：保留 `GodotLog` 用户入口，同时让底层输出走 Core 可组合管线 +4. 为选定方案补充 targeted tests 与 `docs/zh-CN/` adoption guidance + +## 验证 + +- `dotnet build GFramework.sln -c Release` + - 结果：通过，`0 warning / 0 error` + - 备注：2026-05-03 在创建本 active topic 前已验证归档收尾分支；后续实现改动需要按受影响项目重新验证 + +## 下一步 + +1. 从 `GFramework.Core` 与 `GFramework.Godot.Logging` 源码开始做只读盘点 +2. 在 trace 中记录候选设计和不采用的扩张路径 +3. 确认实现边界后再修改代码与文档 diff --git a/ai-plan/public/godot-logging-core-sink/traces/godot-logging-core-sink-trace.md b/ai-plan/public/godot-logging-core-sink/traces/godot-logging-core-sink-trace.md new file mode 100644 index 00000000..e487900b --- /dev/null +++ b/ai-plan/public/godot-logging-core-sink/traces/godot-logging-core-sink-trace.md @@ -0,0 +1,31 @@ +# 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 中继续扩张新需求 + +### 验证 + +- `dotnet build GFramework.sln -c Release` + - 结果：通过，`0 warning / 0 error` + - 备注：本次 build 在创建 active topic 前执行，用于验证归档维护对解决方案无影响；实现阶段需要重新跑受影响项目验证 + +### 下一步 + +1. 只读盘点 Core logging 抽象与 Godot logger/provider 的耦合点 +2. 记录候选设计，明确哪些能力进入 Core，哪些保留在 Godot 宿主层 +3. 确认方案后进入实现与文档更新