docs(ai-plan): 启动 Godot logging Core sink 主题

- 归档 Godot logging 合规收尾主题并保留验证结果

- 新增 Godot logging Core sink active topic 恢复入口

- 更新 public boot 索引和当前分支映射
This commit is contained in:
gewuyou 2026-05-03 10:51:16 +08:00
parent 918a61f3b2
commit 40cce565e6
5 changed files with 122 additions and 18 deletions

View File

@ -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。

View File

@ -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

View File

@ -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. 当前归档维护已完成;后续只需提交并发布归档分支

View File

@ -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. 确认实现边界后再修改代码与文档

View File

@ -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. 确认方案后进入实现与文档更新