mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-06 16:16:44 +08:00
docs(governance): 收敛恢复入口并补充评审示例
- 更新 documentation governance 的 active tracking 与 trace，只保留当前恢复点、风险、验证结果与归档指针 - 归档 RP-001 到 RP-016 的状态与时间线摘要，降低 boot 恢复时的噪音 - 补充 UnifiedSettingsDataRepository 的统一文件布局示例，并补齐 Godot SourceGenerators 的生命周期接法代码片段
This commit is contained in:
gewuyou
parent
4b5a760643
commit
a6b87c23e4
@ -129,6 +129,35 @@
|
||||
|
||||
也就是说，本包负责生成辅助方法，但调用时机仍由项目侧决定。
|
||||
|
||||
最小接法可以直接写成：
|
||||
|
||||
```csharp
|
||||
using GFramework.Godot.Attribute;
|
||||
using Godot;
|
||||
|
||||
public partial class MainMenu : Control
|
||||
{
|
||||
[GetNode]
|
||||
private Button _startButton = null!;
|
||||
|
||||
public override void _Ready()
|
||||
{
|
||||
__InjectGetNodes_Generated();
|
||||
__BindNodeSignals_Generated();
|
||||
}
|
||||
|
||||
public override void _ExitTree()
|
||||
{
|
||||
__UnbindNodeSignals_Generated();
|
||||
}
|
||||
|
||||
[BindNodeSignal(nameof(_startButton), nameof(Button.Pressed))]
|
||||
private void OnStartPressed()
|
||||
{
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 按场景选特性
|
||||
|
||||
- 项目级元数据：
|
||||
|
||||
@ -0,0 +1,77 @@
|
||||
# Documentation Full Coverage Governance Status History Through RP-016
|
||||
|
||||
以下内容从 active tracking 中迁出，用于保留 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-001` 到
|
||||
`DOCUMENTATION-FULL-COVERAGE-GOV-RP-016` 的阶段性状态、治理结论与恢复背景。默认 `boot` 只需要读取 active
|
||||
tracking 中的最新摘要；若需要追溯已完成波次的详细背景，再回到本归档文件。
|
||||
|
||||
## 阶段里程碑
|
||||
|
||||
### `RP-001` 到 `RP-007`
|
||||
|
||||
- 建立长期 active topic `documentation-full-coverage-governance`，并在 `ai-plan/public/README.md` 中将当前分支
|
||||
`docs/sdk-update-documentation` 映射到该 topic。
|
||||
- 明确消费属性边界：
|
||||
- `GFramework.Ecs.Arch.Abstractions` 是可打包直接消费模块，需要 README 与文档入口。
|
||||
- `GFramework.Core.SourceGenerators.Abstractions`、
|
||||
`GFramework.Godot.SourceGenerators.Abstractions`、`GFramework.SourceGenerators.Common`
|
||||
都按 `IsPackable=false` 的内部支撑模块处理。
|
||||
- 收口 `Core` / `Core.Abstractions` README、landing page 与类型族级 XML inventory。
|
||||
- 收口 `Ecs.Arch` / `Ecs.Arch.Abstractions` README、landing page、抽象页与 `UseArch(...)` 早于
|
||||
`Initialize()` 的采用约束。
|
||||
- 收口 `Cqrs` family 的 runtime / abstractions / source generator 入口，并为缺失的内部类型补齐 XML 注释。
|
||||
- 收口 `Game` family 的 README、landing page、抽象页与类型族级 XML inventory。
|
||||
- 将 `Game` family 从“文档存在但入口失真”推进到“runtime / abstractions / source generator 都有当前可审计入口”。
|
||||
|
||||
### `RP-008` 到 `RP-013`
|
||||
|
||||
- 消化 PR #271 的文档 follow-up，修正 `gframework-pr-review` 脚本与 skill 中的 WSL Git 策略，使其与
|
||||
`AGENTS.md` 保持一致。
|
||||
- 将 `Godot` family 的核心恢复摘要迁回 active topic，避免默认恢复路径继续依赖 archive 细节。
|
||||
- 重写 `GFramework.Godot/README.md` 与 `GFramework.Godot.SourceGenerators/README.md`，补齐当前包关系、
|
||||
子系统地图、最小接入路径与站内文档入口。
|
||||
- 更新根 `README.md`、`docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md`，把
|
||||
`GFramework.Godot.SourceGenerators` 的 owner 与能力边界收敛到当前源码口径。
|
||||
- 完成 `Godot` docs surface 的 validation-only 巡检，确认 landing、tutorial、API reference 与 README
|
||||
当前保持一致叙述，没有出现新的入口漂移。
|
||||
|
||||
### `RP-014` 到 `RP-016`
|
||||
|
||||
- 重写 `docs/zh-CN/godot/storage.md`，补齐 frontmatter、`GodotFileStorage` 的路径语义、repository 分工与
|
||||
`GodotYamlConfigLoader` 分流边界。
|
||||
- 重写 `docs/zh-CN/godot/setting.md`，改回当前 `ISettingsModel` / `RegisterApplicator(...)` 口径，并补齐
|
||||
`LocalizationMap` fallback 与当前 consumer wiring。
|
||||
- 对 `Godot` docs surface 再做一轮 validation-only 巡检，确认 `storage.md`、`setting.md`、landing、README、
|
||||
tutorial 与 API reference 没有新的回漂。
|
||||
- 重写 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md`，把 `Game` persistence docs
|
||||
surface 收口到当前 repository / storage / serializer / settings 责任边界。
|
||||
- 将 `DataRepository`、`UnifiedSettingsDataRepository`、`SaveRepository<TSaveData>` 与 `FileStorage` /
|
||||
`ScopedStorage` / `SettingsModel<TRepository>` 的分工，统一回写到 README、源码与 `PersistenceTests` 已验证的采用路径。
|
||||
|
||||
## 已确认的长期事实
|
||||
|
||||
- 已归档的 `documentation-governance-and-refresh` 只作为历史证据保留，不再作为默认 `boot` 入口。
|
||||
- `Godot` family 当前核心页面集包括：
|
||||
- `docs/zh-CN/godot/index.md`
|
||||
- `docs/zh-CN/godot/architecture.md`
|
||||
- `docs/zh-CN/godot/scene.md`
|
||||
- `docs/zh-CN/godot/ui.md`
|
||||
- `docs/zh-CN/godot/storage.md`
|
||||
- `docs/zh-CN/godot/setting.md`
|
||||
- `docs/zh-CN/godot/signal.md`
|
||||
- `docs/zh-CN/godot/extensions.md`
|
||||
- `docs/zh-CN/godot/logging.md`
|
||||
- `docs/zh-CN/tutorials/godot-integration.md`
|
||||
- `Game` persistence docs surface 当前最值得优先复核的页面集包括：
|
||||
- `docs/zh-CN/game/data.md`
|
||||
- `docs/zh-CN/game/storage.md`
|
||||
- `docs/zh-CN/game/serialization.md`
|
||||
- `docs/zh-CN/game/setting.md`
|
||||
- `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发
|
||||
`MSB4276` / `MSB4018`；这是已知环境阻塞，不是本 topic 当前文档回归。
|
||||
- 当前 WSL 会话里 `git.exe` 可解析但不可执行，仓库默认 Git 策略应继续优先使用显式
|
||||
`--git-dir` / `--work-tree` 绑定。
|
||||
|
||||
## 关联归档
|
||||
|
||||
- 早期详细验证历史：`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
|
||||
- 时间线归档：`ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md`
|
||||
@ -0,0 +1,92 @@
|
||||
# Documentation Full Coverage Governance Trace History Through RP-016
|
||||
|
||||
以下内容从 active trace 中迁出，用于保留 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-001` 到
|
||||
`DOCUMENTATION-FULL-COVERAGE-GOV-RP-016` 的阶段时间线、关键决策与主要验证结果。默认 `boot` 只需要读取
|
||||
active trace 中的最新恢复点；若需要追溯旧阶段的执行顺序，再回到本归档文件。
|
||||
|
||||
## 2026-04-22
|
||||
|
||||
### `RP-001`
|
||||
|
||||
- 新建 active topic `documentation-full-coverage-governance`。
|
||||
- 在 `ai-plan/public/README.md` 中将当前 worktree 绑定到该 topic。
|
||||
- 盘点可消费模块与内部支撑模块的边界，作为后续 README / docs 治理基线。
|
||||
|
||||
### `RP-002`
|
||||
|
||||
- 完成 `Core` / `Core.Abstractions` README、landing page 与类型族级 XML inventory 的第一轮收口。
|
||||
- 运行 `docs` 站点构建与局部文档校验，结果通过。
|
||||
|
||||
### `RP-003`
|
||||
|
||||
- 完成 `Ecs.Arch` / `Ecs.Arch.Abstractions` 文档刷新。
|
||||
- 确认 `UseArch(...)` 必须早于 `Initialize()` 的采用顺序，并将该约束写回文档。
|
||||
- 运行 `docs` 站点构建，结果通过。
|
||||
|
||||
### `RP-004`
|
||||
|
||||
- 完成 `Cqrs` family landing、generator topic 与 API 参考入口刷新。
|
||||
- 为 `GFramework.Cqrs` 与 `GFramework.Cqrs.SourceGenerators` 缺失的内部类型补齐 XML 注释。
|
||||
- `GFramework.Cqrs.SourceGenerators` Release build 通过。
|
||||
- `GFramework.Cqrs` Release build 仍受环境级 fallback package folder 问题阻塞，记录为已知非回归风险。
|
||||
|
||||
## 2026-04-23
|
||||
|
||||
### `RP-005`
|
||||
|
||||
- 完成 `Game` family README、landing page、抽象页与类型族级 XML inventory 刷新。
|
||||
- 文档校验与 `docs` 站点构建通过。
|
||||
|
||||
### `RP-006`
|
||||
|
||||
- 更新 `AGENTS.md` 的 WSL Git 回退顺序：
|
||||
- 优先显式 `--git-dir` / `--work-tree` 绑定。
|
||||
- `git.exe` 仅在当前会话可执行时作为 fallback。
|
||||
- `docs` 站点构建通过。
|
||||
|
||||
### `RP-007`
|
||||
|
||||
- 完成 `Game` family validation-only 巡检。
|
||||
- 确认 `config-system.md`、`scene.md`、`ui.md` 与 `source-generators/index.md` 当前没有新的采用漂移。
|
||||
|
||||
### `RP-008` 到 `RP-013`
|
||||
|
||||
- 消化 PR #271 的 review follow-up，修正 `gframework-pr-review` 脚本与 skill 中的 Git 策略。
|
||||
- 将 `Godot` family 的核心恢复摘要迁回 active topic。
|
||||
- 重写 `GFramework.Godot/README.md` 与 `GFramework.Godot.SourceGenerators/README.md`。
|
||||
- 更新根 `README.md`、`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/api-reference/index.md` 的
|
||||
`Godot` 入口与 owner 描述。
|
||||
- 针对 `Godot` docs surface 执行 validation-only 巡检，确认当前 landing / topic / tutorial / API reference
|
||||
与 README 保持一致。
|
||||
|
||||
### `RP-014`
|
||||
|
||||
- 重写 `docs/zh-CN/godot/storage.md` 与 `docs/zh-CN/godot/setting.md`。
|
||||
- 运行 `scan_module_evidence.py Godot`、相关文档校验与 `docs` 站点构建，结果通过。
|
||||
|
||||
### `RP-015`
|
||||
|
||||
- 再次执行 `Godot` docs surface validation-only 巡检。
|
||||
- 确认 `storage.md`、`setting.md`、landing、README、tutorial 与 API reference 没有新的回漂。
|
||||
|
||||
### `RP-016`
|
||||
|
||||
- 重写 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md`。
|
||||
- 运行 `scan_module_evidence.py Game`、相关文档校验与 `docs` 站点构建，结果通过。
|
||||
- 当前 `Game` persistence docs surface 已回到与源码、README 和 `PersistenceTests` 一致的责任边界叙述。
|
||||
|
||||
## 主要验证汇总
|
||||
|
||||
- `cd docs && bun run build`
|
||||
- 多轮执行通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh ...`
|
||||
- 针对本 topic 涉及的 landing / topic / abstractions 页面多轮执行通过。
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`
|
||||
- 通过。
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`
|
||||
- 通过。
|
||||
|
||||
## 归档关联
|
||||
|
||||
- 状态归档：`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md`
|
||||
- 早期详细验证历史：`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
|
||||
@ -3,7 +3,7 @@
|
||||
## 目标
|
||||
|
||||
建立一个长期 active topic，持续治理 `GFramework` 的 README、`docs/zh-CN`、站点导航、XML 文档和 API
|
||||
参考链路，避免历史上的阶段性刷新完成后再次回漂。
|
||||
参考链路，避免阶段性刷新完成后再次回漂。
|
||||
|
||||
- 用源码、测试、`*.csproj` 和必要的 `ai-libs/` 证据校正文档
|
||||
- 以模块族为单位闭环 README、landing page、专题页、教程入口和 API 参考链路
|
||||
@ -12,184 +12,60 @@
|
||||
|
||||
## 当前恢复点
|
||||
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-016`
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-017`
|
||||
- 当前阶段：`Phase 5 - Governance Maintenance`
|
||||
- 当前焦点：
|
||||
- 保持 `Game` family 的 persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述
|
||||
- 将 `data.md`、`storage.md`、`serialization.md`、`setting.md` 视为 `Game` family 当前需要一起巡检的核心页面集，而不是分散的旧 API 手册页
|
||||
- 重点观察 `DataRepository` / `UnifiedSettingsDataRepository` / `SaveRepository<TSaveData>`、`FileStorage` / `ScopedStorage` 与 `SettingsModel<TRepository>` 的职责边界是否再次回漂
|
||||
- 在 `Game` runtime public API 或 README 再次变动前，优先做 targeted 巡检，不重复改写已稳定的 landing page
|
||||
- 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述
|
||||
- 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性
|
||||
- 保持 active tracking / trace 只承载当前恢复入口，把阶段细节留在 `archive/`
|
||||
|
||||
## 当前状态摘要
|
||||
|
||||
- 已归档的 `documentation-governance-and-refresh` 仅保留为历史证据，不再作为默认 `boot` 入口
|
||||
- `2026-04-23` 的 `Game` persistence docs wave 新增结论：
|
||||
- `docs/zh-CN/game/storage.md` 之前仍停留在旧版“通用存储 API 手册”写法，没有反映 `FileStorage` / `ScopedStorage` 与上层 repository 的分工，也没有强调当前同步 API 只是异步阻塞包装
|
||||
- `docs/zh-CN/game/data.md` 之前缺少 `DataRepository`、`UnifiedSettingsDataRepository` 与 `SaveRepository<TSaveData>` 三层分工，以及 `PersistenceTests` 已覆盖的备份 / 批量事件 / 存档迁移语义
|
||||
- `docs/zh-CN/game/serialization.md` 之前仍沿用“业务层手工 Serialize 再写回 storage”的旧示例，没有反映当前 `FileStorage` 已直接复用注入的 `ISerializer`
|
||||
- `docs/zh-CN/game/setting.md` 虽然已回到 `ISettingsModel` / `RegisterApplicator(...)` 口径，但缺少 frontmatter，且还没有和新的 `Game` persistence docs surface 使用同一套结构
|
||||
- `2026-04-23` 的 `Game` persistence docs wave 治理动作：
|
||||
- 重写 `docs/zh-CN/game/storage.md`，将其改为 `FileStorage` / `ScopedStorage` 的职责、路径语义、作用域复用与 repository 边界页
|
||||
- 重写 `docs/zh-CN/game/data.md`，补齐 `DataRepository`、`UnifiedSettingsDataRepository`、`SaveRepository<TSaveData>` 与 `DataRepositoryOptions` / `SaveConfiguration` 的当前契约
|
||||
- 重写 `docs/zh-CN/game/serialization.md`，收敛到 `JsonSerializer` 的配置生命周期、运行时类型序列化与和 storage / repository 的分工
|
||||
- 重写 `docs/zh-CN/game/setting.md`，使其与 `SettingsModel<TRepository>`、`SettingsSystem`、迁移缓存和统一设置仓库的当前实现保持一致
|
||||
- 本轮已消化的 PR #271 review follow-up：
|
||||
- 为 `.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py` 补齐 WSL worktree 下的显式 Linux Git 绑定，避免 `git.exe` 在当前会话触发 `Exec format error`
|
||||
- 同步更新 `.agents/skills/gframework-pr-review/SKILL.md`，改为与 `AGENTS.md` 一致的 Git 策略，并把命令示例统一到 `.agents/...` 路径
|
||||
- 为 `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` 补充 marker 类型放置与命名约定说明
|
||||
- 从 `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 删除误放的 source-generator 内部模块提醒，并微调 `docs/zh-CN/ecs/index.md` 的边界说明语序
|
||||
- 为 `ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md` 的归档验证补写结果态
|
||||
- 将 RP-001 至 RP-007 的详细验证历史迁入 `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
|
||||
- `2026-04-23` 再次执行 `$gframework-pr-review` 后，确认 PR `#271` 已关闭，latest reviewed commit `df91d3706ba9db71737e803ef2f40f4841ecbbf1` 仍显示 `2` 条 open thread，但两条都对应已在当前 HEAD 满足的 `ai-plan` 变更，属于 closed PR 上未自动收敛的陈旧线程信号
|
||||
- 本轮已确认的消费属性结论：
|
||||
- `GFramework.Ecs.Arch.Abstractions`：可打包直接消费模块，需要 README 和文档入口
|
||||
- `GFramework.Core.SourceGenerators.Abstractions`：`IsPackable=false`，按内部支撑模块处理
|
||||
- `GFramework.Godot.SourceGenerators.Abstractions`：`IsPackable=false`，按内部支撑模块处理
|
||||
- `GFramework.SourceGenerators.Common`：`IsPackable=false`，按内部支撑模块处理
|
||||
- 本轮已确认的 `Godot` family 恢复摘要：
|
||||
- `docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`storage.md`、`setting.md`、`signal.md`、`extensions.md`、`logging.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 是当前需要保留的核心页面集
|
||||
- `GFramework.Godot.SourceGenerators` 继续作为 `[GetNode]`、`[BindNodeSignal]`、`AutoLoads` 与 `InputActions` 的 owner；`GFramework.Godot.SourceGenerators.Abstractions` 仍按内部支撑模块处理
|
||||
- `Godot` Scene / UI 采用边界已经稳定：当前没有 `GodotSceneRouter` 或 `GodotUiRouter`；`GodotSceneFactory` 在 provider 缺失时会回退到 `SceneBehaviorFactory`，而 `GodotUiFactory` 仍要求 `IUiPageBehaviorProvider`
|
||||
- `2026-04-23` 的 validation-only 巡检新增结论：
|
||||
- 根 `README.md`、`docs/zh-CN/godot/index.md`、`docs/zh-CN/tutorials/godot-integration.md`、`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/api-reference/index.md` 当前仍保持同一套 `Godot` owner / adoption path 叙述，没有发现新的入口漂移
|
||||
- `scan_module_evidence.py Godot` 显示 `docs/zh-CN/godot/storage.md` 与 `setting.md` 仍属于 `Godot` runtime docs surface，应并入 active topic 的最小恢复摘要，避免后续 `boot` 漏掉当前 landing page 的关键入口
|
||||
- `2026-04-23` 的子页巡检新增结论：
|
||||
- `docs/zh-CN/godot/storage.md` 之前仍停留在旧版 API 手册写法，缺少 frontmatter、`IStorage` / repository 边界和 `GodotYamlConfigLoader` 的分流说明
|
||||
- `docs/zh-CN/godot/setting.md` 之前仍把 `GodotAudioSettings` / `GodotGraphicsSettings` 描述成直接持有设置数据对象的旧构造方式，没有反映当前 `ISettingsModel` + `RegisterApplicator(...)` 接法
|
||||
- `2026-04-23` 的交叉链接巡检新增结论：
|
||||
- `GFramework.Godot/README.md` 仍停留在旧版简略描述，缺少当前包关系、子系统地图、最小接入路径与 `docs/zh-CN` 入口
|
||||
- `GFramework.Godot.SourceGenerators/README.md` 虽有示例，但没有覆盖 `AutoScene`、`AutoUiPage`、`AutoRegisterExportedCollections` 等当前生成器分组，也没有把运行时 / 生成器边界说清
|
||||
- `docs/zh-CN/api-reference/index.md` 的 `Godot` 行此前只把生成器入口指向泛化的 `source-generators/index.md`，不利于从 API 参考直接落到 `Godot` 专题页
|
||||
- `2026-04-23` 的后续入口巡检新增结论：
|
||||
- 根 `README.md` 的模块地图仍把 `GFramework.Godot.SourceGenerators` 写成“Godot 场景专用源码生成器”，范围过窄，不符合当前 `project.godot` 元数据、节点注入、信号绑定、Scene / UI 包装与导出集合注册的真实职责
|
||||
- `docs/zh-CN/source-generators/index.md` 的选包说明此前只提到 `AutoLoad / Input Action` 与节点 / 信号样板，没有把 Scene / UI 包装与导出集合注册辅助纳入同一入口
|
||||
- 本轮已完成的治理动作：
|
||||
- 新建 `GFramework.Ecs.Arch.Abstractions/README.md`
|
||||
- 在根 `README.md` 中补齐 `GFramework.Ecs.Arch.Abstractions` 入口，并声明内部支撑模块 owner
|
||||
- 为抽象接口栏目补齐 `Ecs.Arch.Abstractions` 页面与 sidebar 入口
|
||||
- 将 `docs/zh-CN/api-reference/index.md` 重写为模块到 XML / README / 教程的阅读链路入口
|
||||
- 为 `GFramework.Core/README.md` 补齐 `Services`、`Configuration`、`Environment`、`Pool`、`Rule`、`Time` 等当前目录映射
|
||||
- 为 `GFramework.Core.Abstractions/README.md` 补齐契约族地图与 XML 阅读重点
|
||||
- 将 `docs/zh-CN/abstractions/core-abstractions.md` 从过时的接口摘录页重写为契约边界 / 包关系 / 最小接入路径页面
|
||||
- 为 `docs/zh-CN/core/index.md` 补齐 frontmatter、能力域导航和 API / XML 阅读入口
|
||||
- 为 `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` 补齐类型族级 XML 覆盖基线入口
|
||||
- 为 `docs/zh-CN/core/index.md`、`docs/zh-CN/abstractions/core-abstractions.md` 增加“类型族 -> XML 覆盖状态 -> 代表类型”的 inventory
|
||||
- 基于顶层目录轻量盘点确认：`Core` / `Core.Abstractions` 当前公开 / 内部类型声明都已带 XML 注释，成员级审计留待后续波次
|
||||
- 重写 `docs/zh-CN/ecs/index.md`，收敛当前 ECS family 的包边界、采用顺序和 XML inventory
|
||||
- 重写 `docs/zh-CN/ecs/arch.md`，明确 `UseArch(...)` 需早于 `Initialize()` 的真实接入时机
|
||||
- 刷新 `GFramework.Ecs.Arch/README.md`，使运行时 README 与源码 / 测试一致
|
||||
- 为 `GFramework.Ecs.Arch.Abstractions/README.md` 与 `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 补齐类型族级 XML inventory
|
||||
- 重写 `docs/zh-CN/core/cqrs.md`，将其收敛为 `Cqrs` family landing，并补齐运行时 / 契约层 / 生成器的 XML inventory
|
||||
- 新建 `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`，为 `Cqrs.SourceGenerators` 补齐站内专题入口
|
||||
- 更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md` 与 VitePress sidebar，使 `Cqrs` family 的 generator 入口可导航
|
||||
- 为 `GFramework.Cqrs/Internal/CqrsHandlerRegistrar.cs` 与 `GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.cs` 中缺失的内部类型补齐 XML 注释，使本轮轻量 inventory 达到声明级闭环
|
||||
- 为 `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md` 补齐 `Game` family 的类型族级 XML inventory
|
||||
- 为 `docs/zh-CN/game/index.md` 补齐 frontmatter，并增加 `Game` / `Game.Abstractions` / `Game.SourceGenerators` 的 XML 覆盖基线入口
|
||||
- 将 `docs/zh-CN/abstractions/game-abstractions.md` 从失真的旧接口摘录页重写为契约边界 / 包关系 / 最小接入路径页面
|
||||
- 基于顶层目录轻量盘点确认：`GFramework.Game` 为 `56/56`、`GFramework.Game.Abstractions` 为 `80/80`、`GFramework.Game.SourceGenerators` 为 `2/2`，当前公开 / 内部类型声明都已带 XML 注释
|
||||
- 更新 `AGENTS.md` 的 WSL Git 策略，将显式 `--git-dir` / `--work-tree` 绑定提升为高于 `git.exe` 的默认优先级
|
||||
- 记录当前环境偏差：本会话 `git.exe` 可解析但执行会触发 `Exec format error`，而 plain Linux `git` 会命中 worktree 路径翻译错误，需要显式仓库绑定
|
||||
- 完成 `Game` family 巡检，确认 `docs/zh-CN/game/config-system.md`、`scene.md`、`ui.md` 与 `docs/zh-CN/source-generators/index.md` 的核心采用说明、包关系与交叉引用仍与当前源码 / README 一致，没有发现需要立刻修正的回漂
|
||||
- 将 `Godot` family 的最小恢复摘要迁回 active topic，保留核心页面集、生成器 owner、Scene / UI 真实边界与归档指针，避免长期治理默认恢复路径继续依赖 archive 明细
|
||||
- 重写 `GFramework.Godot/README.md`，补齐包定位、相邻包关系、子系统地图、最小接入路径与站内文档入口，并明确它不拥有生成器职责
|
||||
- 重写 `GFramework.Godot.SourceGenerators/README.md`，按 `project.godot` 元数据、节点注入 / 信号绑定、行为包装与批量注册四组能力重建入口
|
||||
- 更新 `docs/zh-CN/api-reference/index.md` 的 `Godot` 模块映射，使 API 参考能直接落到 `Godot` 专用生成器专题页，而不是仅回到总览页
|
||||
- 修正根 `README.md` 中 `GFramework.Godot.SourceGenerators` 的模块描述，使其与当前生成器职责边界一致
|
||||
- 扩充 `docs/zh-CN/source-generators/index.md` 的 Godot 选包说明，把 Scene / UI 包装与导出集合注册辅助纳入入口摘要
|
||||
- 重写 `docs/zh-CN/godot/storage.md`，补齐 frontmatter、`GodotFileStorage` 的路径语义、repository 分工与 `GodotYamlConfigLoader` 分流边界
|
||||
- 重写 `docs/zh-CN/godot/setting.md`，改回当前 `ISettingsModel` / `RegisterApplicator(...)` 口径，并补上 `LocalizationMap` fallback 与 `CoreGrid` 注册示例
|
||||
- `2026-04-23` 再次通过 `$gframework-boot` 恢复当前 worktree 后，按 `Godot` docs surface 执行 validation-only 巡检，确认 `GFramework.Godot/README.md`、`docs/zh-CN/godot/index.md`、`storage.md`、`setting.md`、`docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 仍保持一致的 owner / adoption path 叙述，没有出现自 `RP-014` 之后的新漂移
|
||||
|
||||
## Inventory（第一版）
|
||||
|
||||
| 模块族 | 当前状态 | 当前证据 | 下一动作 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Core` / `Core.Abstractions` | `README / landing / 类型族级 XML inventory 已收口，成员级审计待补齐` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已对齐当前目录与类型族基线 | 进入巡检；如有新 API 变更，再追加成员级 XML 审计 |
|
||||
| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `README / landing / generator topic / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md`、`docs/zh-CN/core/cqrs.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/api-reference/index.md` 已对齐当前源码与测试 | 转入巡检；下一波切到 `Game` family 的 XML / 教程链路审计 |
|
||||
| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `README / landing / abstractions / persistence topic pages / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`docs/zh-CN/game/index.md`、`docs/zh-CN/abstractions/game-abstractions.md`、`docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 已对齐当前源码、README 与 `PersistenceTests` | 转入巡检；优先观察后续分支是否再次把 `Game` persistence docs 写回旧 API 手册口径 |
|
||||
| `Godot` / `Godot.SourceGenerators` | `README / 生成器 README / landing / topic / tutorial / API reference 入口已重新对齐，成员级 XML 审计不在本轮范围` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md`、`docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`storage.md`、`setting.md`、`signal.md`、`extensions.md`、`logging.md`、`docs/zh-CN/tutorials/godot-integration.md` | 进入巡检周期，优先观察后续分支是否再次把 README / API 入口写回过时边界 |
|
||||
| `Ecs.Arch` / `Ecs.Arch.Abstractions` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md`、`docs/zh-CN/ecs/**`、`docs/zh-CN/abstractions/ecs-arch-abstractions.md` 已对齐当前源码与测试 | 转入巡检；后续仅在运行时公共 API 变动时补成员级 XML 细审 |
|
||||
| `SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` | `已判定为内部支撑` | `*.csproj` 明确 `IsPackable=false` | 由所属模块 README 与生成器栏目说明 owner，不建独立采用页 |
|
||||
|
||||
## 缺口分级
|
||||
|
||||
- `P0`
|
||||
- 错误采用路径、错误包关系、错误 API / 生命周期语义
|
||||
- 站点导航死链、空 landing page、明显错误的模块 owner
|
||||
- `P1`
|
||||
- 直接消费模块缺 README 或缺对应 docs 入口
|
||||
- README / docs 示例与源码实现不一致
|
||||
- 教程仍引用已经过时的默认接线方式
|
||||
- `P2`
|
||||
- 结构重复、交叉链接不足、API 参考链路过薄
|
||||
- 站内页面存在事实正确但组织方式不利于定位的内容
|
||||
- `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
|
||||
- `Game` persistence docs surface 当前以 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md`
|
||||
作为最小巡检集合；若后续 README、runtime public API 或 `PersistenceTests` 变动，应优先复核这一组页面。
|
||||
- `Godot` runtime 与 generator 入口当前以 `GFramework.Godot/README.md`、
|
||||
`GFramework.Godot.SourceGenerators/README.md`、`docs/zh-CN/godot/index.md`、
|
||||
`docs/zh-CN/source-generators/index.md`、`docs/zh-CN/tutorials/godot-integration.md` 维持统一 owner / adoption path。
|
||||
- `2026-04-23` 基于 PR `#272` 的 review follow-up 已完成：
|
||||
- 为 `docs/zh-CN/game/data.md` 补充 `UnifiedSettingsDataRepository` 的统一文件布局示例
|
||||
- 为 `GFramework.Godot.SourceGenerators/README.md` 补充手写 `_Ready()` / `_ExitTree()` 时显式调用生成方法的最小样例
|
||||
- 将过长的 active tracking / trace 瘦身，并把历史摘要迁回 `archive/`
|
||||
- 当前唯一剩余的 PR 信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于托管侧元数据，不是本地文件缺陷。
|
||||
|
||||
## 当前风险
|
||||
|
||||
- 当前 `Core` / `Core.Abstractions` 只完成了类型族级 XML 基线，不等于成员级契约全审计
|
||||
- 缓解措施：后续只在共享抽象或高风险生命周期接口发生改动时补成员级细审，不在本轮扩张范围
|
||||
- `Godot` family 的详细治理历史仍保留在 archive，active topic 只回填了最小恢复摘要
|
||||
- 缓解措施：active topic 记录核心页面集、owner、运行时边界与 archive 指针；只有在需要阶段级历史时再读取归档材料
|
||||
- 新功能分支若修改 README / docs / 公共 API 却不挂文档 topic，仍可能回漂
|
||||
- 缓解措施：将本 topic 作为长期 active topic 保留，并在后续巡检中记录回漂来源
|
||||
- VitePress 页面不能直接链接到 `docs/` 目录之外的模块 `README.md`
|
||||
- 缓解措施：站内页面用模块路径文本或站内 API 入口表达，仓库级 README 仍保留仓库文件链接
|
||||
- `GFramework.Cqrs` 在当前 WSL / dotnet 环境下，本地 build 仍会读取失效的 fallback package folder 配置，导致无法完成该项目的标准编译验证
|
||||
- 缓解措施：本轮先以 `GFramework.Cqrs.SourceGenerators` 编译通过和 docs site build 通过作为有效验证，并在后续环境治理或构建脚本清理时单独处理 `RestoreFallbackFolders` / 资产文件问题
|
||||
- 当前 WSL 会话中 `git.exe` 虽然可解析，但不能执行
|
||||
- 缓解措施：把显式 `--git-dir` / `--work-tree` 绑定上升为仓库默认回退策略，并仅把 `git.exe` 保留为可执行时的次级 fallback
|
||||
- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理仍以“类型声明级基线”为主，不等于成员级契约全审计。
|
||||
- `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发
|
||||
`MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。
|
||||
- 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。
|
||||
|
||||
## 验证说明
|
||||
## 归档指针
|
||||
|
||||
- 详细验证历史（`RP-001` 到 `RP-007`）：
|
||||
`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
|
||||
- 阶段状态归档（`RP-001` 到 `RP-016`）：
|
||||
`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md`
|
||||
- 时间线归档（`RP-001` 到 `RP-016`）：
|
||||
`ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md`
|
||||
|
||||
## 最新验证
|
||||
|
||||
- 详细验证历史已归档到 `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
|
||||
- 最新 PR review 结论：
|
||||
- `2026-04-23` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
|
||||
- 结果：通过；PR `#271` 已关闭，latest reviewed commit 为 `df91d3706ba9db71737e803ef2f40f4841ecbbf1`，当前 `2` 条 open thread 都是已被本地文件满足的陈旧信号，不再构成本轮阻塞
|
||||
- 最新构建结论：
|
||||
- 结果：通过；PR `#272` 处于 `OPEN`，latest head commit 没有未解决 open thread，当前只剩 `Title check` 的 PR 标题提示。
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md`
|
||||
- 结果：通过。
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot.SourceGenerators/README.md`
|
||||
- 结果：通过。
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot.SourceGenerators/README.md`
|
||||
- 结果：通过。
|
||||
- `2026-04-23` `cd docs && bun run build`
|
||||
- 结果：通过；在重写 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 后再次验证通过，仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
- 最新 `Game` persistence docs wave 结论：
|
||||
- `2026-04-23` 基于 `GFramework.Game` 源码、`GFramework.Game/README.md`、`JsonSerializerTests`、`SettingsModelTests` 与 `PersistenceTests`
|
||||
- 结果：通过；`docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 当前已回到同一套 `Game` runtime 持久化采用路径，不再沿用旧版 API 手册叙述
|
||||
- 最新稳定性巡检结论：
|
||||
- `2026-04-23` 重新执行 `Godot` docs surface 巡检
|
||||
- 结果：通过；根入口链路保持稳定，并额外发现 `docs/zh-CN/godot/storage.md`、`setting.md` 两页存在旧版叙述残留，当前已按源码口径完成最小修复
|
||||
- 最新 validation-only 巡检结论：
|
||||
- `2026-04-23` 通过 `$gframework-boot` 恢复后重新执行 `Godot` docs surface 巡检
|
||||
- 结果：通过；`README / landing / topic / tutorial / API reference` 当前仍保持同一套 `Godot` owner / adoption path 叙述，本轮无需新增文档补丁
|
||||
- 最新恢复治理结论：
|
||||
- `2026-04-23` 重新读取 `ai-plan/public/archive/documentation-governance-and-refresh/**`
|
||||
- 结果：通过；确认 `Godot` family 适合把最小恢复摘要迁回 active topic，但不需要把整段归档历史重新放回默认 `boot` 路径
|
||||
- 已完成的针对性校验：
|
||||
- `2026-04-23` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`：通过
|
||||
- `2026-04-23` `python3 -B -c "from pathlib import Path; compile(Path('.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py').read_text(encoding='utf-8'), '.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py', 'exec')"`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/index.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot/README.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot.SourceGenerators/README.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot.SourceGenerators/README.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh README.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md`：通过
|
||||
- `2026-04-23` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`：通过（boot 后复核）
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md`：通过（boot 后复核）
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md`：通过（boot 后复核）
|
||||
- `2026-04-23` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/serialization.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/setting.md`：通过
|
||||
- `2026-04-23` `cd docs && bun run build`：通过（本轮 `Game` persistence docs wave 复核；仅保留既有 VitePress 大 chunk warning）
|
||||
- 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
|
||||
|
||||
## 下一步
|
||||
|
||||
1. 若后续分支继续调整 `GFramework.Game` 的 persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界
|
||||
2. 当 `Godot` / `Game` family 再次出现交叉入口漂移时，沿用当前 README -> landing -> topic page -> API reference 的最小修复顺序
|
||||
3. 仅在需要阶段级细节时再读取 `documentation-governance-and-refresh` archive，而不是把 archive 重新当作默认 `boot` 入口
|
||||
1. 如果 PR `#272` 的 `Title check` 仍需要消除，到 GitHub 上把标题改成更具体的文档治理描述。
|
||||
2. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
|
||||
`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
|
||||
3. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
|
||||
`docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。
|
||||
|
||||
@ -1,642 +1,52 @@
|
||||
# Documentation Full Coverage Governance Trace
|
||||
|
||||
## 2026-04-22
|
||||
## 2026-04-23
|
||||
|
||||
### 当前恢复点：RP-001
|
||||
### 当前恢复点：RP-017
|
||||
|
||||
- 按长期治理计划新建 active topic `documentation-full-coverage-governance`
|
||||
- 在 `ai-plan/public/README.md` 中将当前分支 `docs/sdk-update-documentation` 映射到该 topic
|
||||
- 复核已知缺口模块的 `*.csproj` 后确认：
|
||||
- `GFramework.Ecs.Arch.Abstractions` 是可打包消费模块，需要独立 README
|
||||
- `GFramework.Core.SourceGenerators.Abstractions`、`GFramework.Godot.SourceGenerators.Abstractions`、
|
||||
`GFramework.SourceGenerators.Common` 都是 `IsPackable=false` 的内部支撑模块
|
||||
- 基于该结论，本轮没有为内部支撑模块新增独立 README，而是在根 README 与 abstractions / API 入口中明确其 owner
|
||||
- 使用 `$gframework-pr-review` 复核当前分支 PR `#272`。
|
||||
- 本地核对后确认三条 review follow-up 仍然成立：
|
||||
- active tracking / trace 过长，已经偏离“恢复入口”用途
|
||||
- `docs/zh-CN/game/data.md` 缺少 `UnifiedSettingsDataRepository` 的统一文件布局示例
|
||||
- `GFramework.Godot.SourceGenerators/README.md` 缺少手写 `_Ready()` / `_ExitTree()` 时显式调用生成方法的最小样例
|
||||
- 本轮执行的修复：
|
||||
- 为 `docs/zh-CN/game/data.md` 补充统一设置文件目录树示例
|
||||
- 为 `GFramework.Godot.SourceGenerators/README.md` 补充最小生命周期代码片段
|
||||
- 将 active tracking / trace 瘦身，并把 `RP-001` 到 `RP-016` 的阶段细节迁入 `archive/`
|
||||
|
||||
### 当前决策
|
||||
### 当前决策（RP-017）
|
||||
|
||||
- 新主题的完成条件采用长期治理口径：`P0` 清零、无 README 缺失、无导航死链，并完成连续两轮稳定巡检
|
||||
- 本轮先做治理基础设施与 inventory，不把整个长期计划伪装成单轮完成
|
||||
- `api-reference` 页面改为“模块 -> README / docs / XML / tutorial”的阅读链路入口，避免继续维护失真的伪签名列表
|
||||
- `Ecs.Arch` family 被列为高优先 backlog：抽象层入口已补齐，但 runtime docs 仍需按源码重写
|
||||
- `Core` / `Core.Abstractions` 波次先收口 README、landing page 和 abstractions 页的目录映射，再补显式 XML 覆盖 inventory
|
||||
- VitePress 站内页面不直接链接仓库根模块 `README.md`；站内仅保留可构建的 docs 链接，模块 README 以文本路径或仓库 README 承接
|
||||
- active recovery artifact 只保留当前恢复点、当前事实、风险、验证结果与下一步；旧阶段细节统一转移到 archive。
|
||||
- `Game` persistence docs surface 继续以 `data.md`、`storage.md`、`serialization.md`、`setting.md` 作为最小巡检集合。
|
||||
- `GFramework.Godot.SourceGenerators/README.md` 的生命周期接法说明应直接复用与 tutorial 一致的最小样例，避免 README 与教程再次分叉。
|
||||
|
||||
### 当前恢复点：RP-002
|
||||
|
||||
- 完成 `Core` / `Core.Abstractions` 的类型族级 XML inventory：
|
||||
- `GFramework.Core/README.md`
|
||||
- `GFramework.Core.Abstractions/README.md`
|
||||
- `docs/zh-CN/core/index.md`
|
||||
- `docs/zh-CN/abstractions/core-abstractions.md`
|
||||
- 通过顶层目录轻量盘点确认：
|
||||
- `GFramework.Core` 当前各目录族的公开 / 内部类型声明都已带 XML 注释
|
||||
- `GFramework.Core.Abstractions` 当前各契约目录族的公开 / 内部类型声明都已带 XML 注释
|
||||
- 这轮 inventory 明确限定为“类型声明级基线”，不把结果表述成成员级 XML 合规审计
|
||||
|
||||
### 当前决策（RP-002）
|
||||
|
||||
- XML inventory 同时落在模块 README 和站内 landing page：
|
||||
- README 提供仓库侧入口，方便从包目录直接恢复上下文
|
||||
- docs landing 提供更细的类型族 / 代表类型 / 阅读重点表格，方便站内导航
|
||||
- `Core` 波次在补齐基线后转入巡检，不继续在本轮展开成员级 ``<param>`` / ``<returns>`` 审计
|
||||
- 下一恢复点切换到 `Ecs` 波次，优先处理仍明显失真的 runtime docs
|
||||
|
||||
### 当前验证
|
||||
|
||||
- 文档校验：
|
||||
- `validate-all.sh docs/zh-CN/abstractions/index.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/api-reference/index.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/core/index.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/abstractions/core-abstractions.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过
|
||||
- `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)`
|
||||
- `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)`
|
||||
|
||||
### 当前验证（RP-002）
|
||||
|
||||
- 文档校验：
|
||||
- `validate-all.sh docs/zh-CN/core/index.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/abstractions/core-abstractions.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 当前恢复点：RP-003
|
||||
|
||||
- 完成 `Ecs.Arch` 波次的运行时文档刷新：
|
||||
- `docs/zh-CN/ecs/index.md`
|
||||
- `docs/zh-CN/ecs/arch.md`
|
||||
- `GFramework.Ecs.Arch/README.md`
|
||||
- 为 `Ecs.Arch.Abstractions` 补齐与运行时页同粒度的 XML inventory：
|
||||
- `GFramework.Ecs.Arch.Abstractions/README.md`
|
||||
- `docs/zh-CN/abstractions/ecs-arch-abstractions.md`
|
||||
- 明确记录一个关键采用事实：
|
||||
- `UseArch(...)` 必须早于 `Initialize()` 调用
|
||||
- 该结论以 `ArchExtensions` 的模块注册方式和 `ExplicitRegistrationTests` 为证据
|
||||
- 将 `Ecs.Arch` family 从“入口存在但失真”推进到“README / landing / abstractions / XML inventory 已对齐源码与测试”
|
||||
|
||||
### 当前决策（RP-003）
|
||||
|
||||
- `Ecs` 波次继续采用与 `Core` 相同的治理粒度：
|
||||
- 模块 README 承担仓库入口
|
||||
- `docs/zh-CN/ecs/index.md` 承担模块族 landing
|
||||
- `docs/zh-CN/ecs/arch.md` 承担运行时默认实现专题页
|
||||
- `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 承担契约边界专题页
|
||||
- `EnableStatistics` 当前仅保留在公开配置面上；文档不再把它写成已验证的运行时行为
|
||||
- 下一恢复点切换到 `Cqrs` 波次，优先解决入口分散和 API / XML 阅读链路不统一的问题
|
||||
|
||||
### 当前验证（RP-003）
|
||||
|
||||
- 文档校验：
|
||||
- `validate-all.sh docs/zh-CN/ecs/index.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/ecs/arch.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 在 `Cqrs` 波次核对模块 README、`docs/zh-CN/core/cqrs.md` 与 `docs/zh-CN/source-generators/**` 的真实 owner
|
||||
2. 决定 `Cqrs` family 是补 dedicated landing 还是拆分现有入口页
|
||||
|
||||
### 当前恢复点：RP-004
|
||||
|
||||
- 完成 `Cqrs` 波次的模块族入口刷新：
|
||||
- 重写 `docs/zh-CN/core/cqrs.md`
|
||||
- 新建 `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`
|
||||
- 更新 `docs/zh-CN/source-generators/index.md`
|
||||
- 更新 `docs/zh-CN/api-reference/index.md`
|
||||
- 更新 `docs/.vitepress/config.mts`
|
||||
- 将 `Cqrs` family 从“README 已存在但 generator 入口分散”推进到“runtime / abstractions / source generator 都有明确站内入口”
|
||||
- 为 `GFramework.Cqrs/Internal/CqrsHandlerRegistrar.cs` 与
|
||||
`GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.cs` 中缺失的内部类型补齐 XML 注释
|
||||
- 基于轻量扫描确认：
|
||||
- `GFramework.Cqrs.Abstractions/Cqrs/` 当前类型声明级 XML 覆盖为 `20/20`
|
||||
- `GFramework.Cqrs` 根入口与 `Internal/` 已补到 `19/19`
|
||||
- `GFramework.Cqrs.SourceGenerators/Cqrs/` 当前类型声明级 XML 覆盖为 `3/3`
|
||||
|
||||
### 当前决策（RP-004）
|
||||
|
||||
- `docs/zh-CN/core/cqrs.md` 继续保留在 `Core` 栏目，但其角色调整为 `Cqrs` family landing，而不再只是 runtime 简介页
|
||||
- `Cqrs.SourceGenerators` 不单独新建一级导航栏目，而是在 `source-generators` 栏目内补一个专用专题页，保持站点 taxonomy 稳定
|
||||
- generator 入口以“专题页 + API reference 链接 + sidebar”三点联动，而不是只在 `source-generators/index.md` 留一个段落链接
|
||||
- XML inventory 仍维持“类型声明级基线”口径，不在本轮扩展成成员级 `param/returns/exception` 细审
|
||||
|
||||
### 当前验证（RP-004）
|
||||
|
||||
- 文档校验：
|
||||
- `validate-all.sh docs/zh-CN/core/cqrs.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过
|
||||
- 轻量 XML inventory：
|
||||
- `GFramework.Cqrs/Internal/`：`14/14`
|
||||
- `GFramework.Cqrs.Abstractions/Cqrs/`：`20/20`
|
||||
- `GFramework.Cqrs.SourceGenerators/Cqrs/`：`3/3`
|
||||
- 构建校验：
|
||||
- `dotnet build GFramework.Cqrs.SourceGenerators/GFramework.Cqrs.SourceGenerators.csproj -c Release -p:RestoreFallbackFolders=`：通过
|
||||
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
|
||||
- `dotnet build GFramework.Cqrs/GFramework.Cqrs.csproj -c Release`：失败；当前 WSL / dotnet 环境仍引用失效的 Windows fallback package folder，并在多目标 inner build 阶段触发 `MSB4276` / `MSB4018`
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 切换到 `Game` family 波次，按 `Core` / `Ecs` / `Cqrs` 已验证模板继续补 XML inventory 与教程链路
|
||||
2. 把 `GFramework.Cqrs` 的本地构建阻塞留给后续环境治理或构建脚本清理，不在本 topic 内扩张为环境修复任务
|
||||
|
||||
### 当前恢复点：RP-005
|
||||
|
||||
- 完成 `Game` 波次的模块族入口刷新：
|
||||
- 更新 `GFramework.Game/README.md`
|
||||
- 更新 `GFramework.Game.Abstractions/README.md`
|
||||
- 更新 `GFramework.Game.SourceGenerators/README.md`
|
||||
- 更新 `docs/zh-CN/game/index.md`
|
||||
- 重写 `docs/zh-CN/abstractions/game-abstractions.md`
|
||||
- 将 `Game` family 从“README / 页面存在但缺少可审计 XML 入口，且 abstractions 页失真”推进到“runtime / abstractions / source generator 都有声明级 XML inventory 与真实采用边界”
|
||||
- 基于轻量扫描确认：
|
||||
- `GFramework.Game` 当前类型声明级 XML 覆盖为 `56/56`
|
||||
- `GFramework.Game.Abstractions` 当前类型声明级 XML 覆盖为 `80/80`
|
||||
- `GFramework.Game.SourceGenerators` 当前类型声明级 XML 覆盖为 `2/2`
|
||||
|
||||
### 当前决策（RP-005）
|
||||
|
||||
- `docs/zh-CN/abstractions/game-abstractions.md` 不再维护虚构接口摘录，而是与源码中的 `Config` / `Data` / `Setting` / `Scene` / `UI` / `Routing` 契约分组保持一致
|
||||
- `Game.SourceGenerators` 继续以 `README + docs/zh-CN/game/config-system.md + docs/zh-CN/source-generators/index.md` 组成入口，不额外新增只为凑数量的专题页
|
||||
- `docs/zh-CN/game/index.md` 补 frontmatter，并承担 `Game` family 的 XML 基线入口；更细的类型族说明继续留在模块 README 与 abstractions 页
|
||||
|
||||
### 当前验证（RP-005）
|
||||
|
||||
- 文档校验：
|
||||
- `validate-all.sh docs/zh-CN/abstractions/game-abstractions.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/game/index.md`：通过
|
||||
- 轻量 XML inventory：
|
||||
- `GFramework.Game`：`56/56`
|
||||
- `GFramework.Game.Abstractions`：`80/80`
|
||||
- `GFramework.Game.SourceGenerators`：`2/2`
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 进入 `Game` family 巡检，优先检查 `config-system.md`、`scene.md`、`ui.md` 与 `source-generators/index.md` 的交叉引用是否回漂
|
||||
2. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，减少对 archive 的依赖
|
||||
|
||||
### 当前恢复点：RP-006
|
||||
|
||||
- 更新 `AGENTS.md` 的 WSL Git 规则：
|
||||
- 将显式 `git --git-dir=<...> --work-tree=<...>` 绑定提升为高于 `git.exe` 的默认优先级
|
||||
- 明确 plain Linux `git` 命中 worktree 路径翻译错误时，应先切到显式绑定而不是直接改用 `git.exe`
|
||||
- 明确 `git.exe` 只有在当前会话可执行时才作为次级 fallback
|
||||
- 记录本次恢复任务的环境偏差：
|
||||
- `git.exe` 在当前 WSL 会话中可解析，但执行会触发 `Exec format error`
|
||||
- plain `git` 会把 worktree 元数据路径翻译错并报“not a git repository”
|
||||
- 显式 `--git-dir` / `--work-tree` 绑定是本次已验证可用的 Git 操作方式
|
||||
|
||||
### 当前决策（RP-006）
|
||||
|
||||
- 把 Git 回退顺序写进 `AGENTS.md`，而不是只留在一次性的聊天上下文里
|
||||
- 不额外扩张 `gframework-boot` skill，因为它本身不内嵌 Git 选择逻辑，继续由 `AGENTS.md` 作为唯一准则
|
||||
- 继续把 `git.exe` 保留为 fallback，而不是完全删除，避免在可执行的 WSL 会话里丢掉可用路径
|
||||
|
||||
### 当前验证（RP-006）
|
||||
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 继续 `Game` family 巡检，优先检查 `config-system.md`、`scene.md`、`ui.md` 与 `source-generators/index.md` 的交叉引用是否回漂
|
||||
2. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，减少对 archive 的依赖
|
||||
|
||||
### 当前恢复点：RP-007
|
||||
|
||||
- 完成 `Game` family 巡检：
|
||||
- 复核 `docs/zh-CN/game/config-system.md`
|
||||
- 复核 `docs/zh-CN/game/scene.md`
|
||||
- 复核 `docs/zh-CN/game/ui.md`
|
||||
- 复核 `docs/zh-CN/source-generators/index.md`
|
||||
- 对照 `GFramework.Game`、`GFramework.Game.Abstractions`、`GFramework.Game.SourceGenerators` README 与相关源码 / 测试后，未发现需要立刻修正的采用语义回漂
|
||||
- 重点确认的真实语义包括：
|
||||
- `GameConfigBootstrap` / `RegisterAllGeneratedConfigTables(...)` / `GFrameworkConfigSchemaDirectory` 的配置入口仍与文档示例一致
|
||||
- `SceneRouterBase` 仍通过 `SemaphoreSlim` 串行化切换，并拒绝重复 `sceneKey` 入栈
|
||||
- `UiRouterBase` 仍将 `Page` 层与 `Overlay` / `Modal` / `Toast` / `Topmost` 分为两套入口，且 `Show(..., UiLayer.Page)` 会直接拒绝
|
||||
|
||||
### 当前决策（RP-007）
|
||||
|
||||
- 本轮不为“巡检通过”硬造文档改动，先把结论写回 active topic，保持恢复点准确
|
||||
- `Game` family 暂时转入稳定巡检，不在没有源码变化的情况下重复改写 landing page
|
||||
- 默认下一步切到 `Godot` family 摘要是否回迁，减少长期治理对 archive topic 的依赖
|
||||
|
||||
### 当前验证（RP-007）
|
||||
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic
|
||||
2. 若不需要迁回，则继续抽查 README / landing page / API reference 之间的 cross-link 是否出现新的漂移
|
||||
|
||||
### 当前恢复点：RP-008
|
||||
|
||||
- 使用 `$gframework-pr-review` 抓取当前分支 PR `#271` 后，确认 latest head review threads 仍有 `4` 条 open：
|
||||
- `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` 的 marker 类型约定说明缺口
|
||||
- `docs/zh-CN/ecs/index.md` 的边界说明语序问题
|
||||
- `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 误放的 source-generator 内部模块提醒
|
||||
- `ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md` 的验证历史过长，以及
|
||||
`ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md` 缺少显式结果态
|
||||
- 在当前 WSL 会话里，`gframework-pr-review` 脚本先命中了 `git.exe` 的 `Exec format error`
|
||||
- 已将 `.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py` 改为优先使用 Linux `git` 的显式
|
||||
`--git-dir` / `--work-tree` 绑定，并仅在无法建立该绑定时回退到旧的可执行解析逻辑
|
||||
- 已同步更新 `.agents/skills/gframework-pr-review/SKILL.md`，使其 Git 策略与命令示例都与当前仓库状态一致
|
||||
- 已把 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-001` 到 `RP-007` 的详细验证历史迁入
|
||||
`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
|
||||
|
||||
### 当前决策（RP-008）
|
||||
|
||||
- 继续把 latest-head unresolved threads 作为主信号，只修仍在本地成立的评论，不为已失效的历史 summary 做无意义回写
|
||||
- active tracking 只保留最新验证摘要与恢复点；详细验证历史留在 topic 自己的 archive，而不是继续堆在默认 boot 路径
|
||||
- `gframework-pr-review` 的脚本行为、技能文案与 `AGENTS.md` 必须保持同一套 WSL Git 策略，避免再次出现“文档说法正确但工具实现仍跑偏”的情况
|
||||
|
||||
### 当前验证（RP-008）
|
||||
### 当前验证（RP-017）
|
||||
|
||||
- PR review 抓取：
|
||||
- `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`：通过
|
||||
- 脚本语法校验：
|
||||
- `python3 -B -c "from pathlib import Path; compile(Path('.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py').read_text(encoding='utf-8'), '.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py', 'exec')"`：通过
|
||||
- `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
|
||||
- 结果：通过；PR `#272` 处于 `OPEN`，latest head commit 没有未解决 open thread，当前只剩 `Title check` 的 PR 标题提示。
|
||||
- 文档校验：
|
||||
- `validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/ecs/index.md`：通过
|
||||
- `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md`
|
||||
- 结果：通过。
|
||||
- README 校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot.SourceGenerators/README.md`
|
||||
- 结果：通过。
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot.SourceGenerators/README.md`
|
||||
- 结果：通过。
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
- `cd docs && bun run build`
|
||||
- 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
|
||||
|
||||
### 归档指针
|
||||
|
||||
- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
|
||||
- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md`
|
||||
- `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md`
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 提交本轮 PR review follow-up
|
||||
2. 推送当前分支后重新执行 `$gframework-pr-review`，观察 PR #271 的 open threads 是否收敛
|
||||
|
||||
### 当前恢复点：RP-009
|
||||
|
||||
- 按 `boot` 恢复 `documentation-full-coverage-governance` 主题
|
||||
- 重新读取 `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md` 与当前 topic 的 active todo / trace 后，确认当前 worktree `docs/sdk-update-documentation` 仍映射到本 topic
|
||||
- 当前 worktree Git 状态干净，且不存在 `ai-plan/private/` 的 worktree 私有恢复材料
|
||||
- 重新执行 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
|
||||
- 抓取结果显示 PR `#271` 已关闭，latest reviewed commit 仍为 `df91d3706ba9db71737e803ef2f40f4841ecbbf1`
|
||||
- 当前 latest commit 仍显示 `2` 条 open thread，但两条都落在 `ai-plan` 文件上，且本地文件已经满足评论要求：
|
||||
- `ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md` 已包含显式 `结果：通过`
|
||||
- `ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md` 已将 RP-001 至 RP-007 的详细验证明细迁入 archive
|
||||
- 因此本轮将 PR #271 follow-up 视为已完成，后续不再为 closed PR 上未自动收敛的陈旧 thread 状态追加仓库改动
|
||||
|
||||
### 当前决策（RP-009）
|
||||
|
||||
- `closed PR + stale open thread` 不再作为需要继续修改仓库内容的信号；除非后续 review 抓取显示新的 latest-head finding
|
||||
- `documentation-full-coverage-governance` 的默认下一步切回治理 backlog，优先判断是否把 `Godot` family 的关键 XML inventory 摘要迁回 active topic
|
||||
- 本轮 `boot` 不引入 subagent；关键恢复信号都能通过本地读取和单次 PR review 抓取直接确认
|
||||
|
||||
### 当前验证（RP-009）
|
||||
|
||||
- PR review 抓取：
|
||||
- `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`：通过；PR `#271` 已关闭，latest reviewed commit 为 `df91d3706ba9db71737e803ef2f40f4841ecbbf1`，当前 `2` 条 open thread 都是已被本地文件满足的陈旧信号
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic
|
||||
2. 若不迁回，则在 active todo / trace 保留足够的 archive 指针，并继续抽查 README / landing page / API reference 的 cross-link 是否出现新的漂移
|
||||
|
||||
### 当前恢复点：RP-010
|
||||
|
||||
- 按 `boot` 恢复当前 topic 后，重新读取：
|
||||
- `AGENTS.md`
|
||||
- `.ai/environment/tools.ai.yaml`
|
||||
- `ai-plan/public/README.md`
|
||||
- `ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md`
|
||||
- `ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md`
|
||||
- 确认当前任务状态属于 `resume`：
|
||||
- 当前分支仍为 `docs/sdk-update-documentation`
|
||||
- `ai-plan/public/README.md` 继续把本 worktree 映射到 `documentation-full-coverage-governance`
|
||||
- 当前 worktree 没有 `ai-plan/private/` 私有恢复材料
|
||||
- 为判断 `Godot` family 是否需要回填恢复摘要，补读归档主题：
|
||||
- `ai-plan/public/archive/documentation-governance-and-refresh/todos/documentation-governance-and-refresh-tracking.md`
|
||||
- `ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md`
|
||||
- `ai-plan/public/archive/documentation-governance-and-refresh/archive/todos/documentation-governance-and-refresh-history-through-2026-04-22.md`
|
||||
- 归档材料表明，`Godot` family 的可恢复关键信号已经稳定，且足以压缩成 active topic 里的最小摘要：
|
||||
- 核心页面集为 `docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`signal.md`、`extensions.md`、`logging.md` 与 `docs/zh-CN/tutorials/godot-integration.md`
|
||||
- `GFramework.Godot.SourceGenerators` 继续作为 `[GetNode]`、`[BindNodeSignal]`、`AutoLoads`、`InputActions` 的 owner
|
||||
- `GFramework.Godot.SourceGenerators.Abstractions` 继续按 `IsPackable=false` 的内部支撑模块处理
|
||||
- `GodotSceneFactory` 在 provider 缺失时回退到 `SceneBehaviorFactory`，而 `GodotUiFactory` 仍要求 `IUiPageBehaviorProvider`
|
||||
- 因此本轮决定：
|
||||
- 不把整段 `documentation-governance-and-refresh` 历史重新迁回 active 路径
|
||||
- 只把足够让未来 `boot` 快速恢复的 `Godot` family 摘要写回 active todo
|
||||
- 继续把阶段级细节留在 archive，保持默认恢复入口轻量
|
||||
|
||||
### 当前决策（RP-010）
|
||||
|
||||
- `Godot` family 的“最小恢复摘要”应当留在 active topic，因为它已经属于长期治理 backlog 的默认上下文，而不仅仅是已完成项目的历史注脚
|
||||
- active topic 只保留对后续判断有用的事实：
|
||||
- 页面范围
|
||||
- generator owner
|
||||
- Scene / UI 真实运行时边界
|
||||
- archive 指针
|
||||
- `documentation-governance-and-refresh` archive 继续作为阶段级历史证据，不重新回到 `boot` 默认扫描路径
|
||||
- 下一步从“是否回填摘要”切换回“继续巡检 cross-link 漂移”，避免治理入口停留在已经完成的元问题上
|
||||
|
||||
### 当前验证（RP-010）
|
||||
|
||||
- 归档恢复检查：
|
||||
- `sed -n '1,260p' ai-plan/public/archive/documentation-governance-and-refresh/todos/documentation-governance-and-refresh-tracking.md`：通过
|
||||
- `sed -n '1,260p' ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md`：通过
|
||||
- `sed -n '1,240p' ai-plan/public/archive/documentation-governance-and-refresh/archive/todos/documentation-governance-and-refresh-history-through-2026-04-22.md`：通过
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 抽查 `Godot` 与 `Game` 相关 README / landing page / API reference 的 cross-link 是否出现新的漂移
|
||||
2. 当后续分支修改相关 README / docs / 公共 API 时，回到对应 module family 追加 targeted 巡检与验证
|
||||
|
||||
### 当前恢复点：RP-011
|
||||
|
||||
- 继续按 `boot` 恢复后的默认下一步执行 `Godot` / `Game` cross-link 巡检，并额外补读：
|
||||
- `GFramework.Godot/README.md`
|
||||
- `GFramework.Godot.SourceGenerators/README.md`
|
||||
- `docs/zh-CN/api-reference/index.md`
|
||||
- `docs/zh-CN/godot/index.md`
|
||||
- `docs/zh-CN/source-generators/index.md`
|
||||
- 结合 `GFramework.Godot.csproj`、`GFramework.Godot.SourceGenerators.csproj`、相关测试与 `scan_module_evidence.py` 输出，确认新的漂移点集中在入口 README：
|
||||
- `GFramework.Godot/README.md` 仍是旧版简略说明，没有记录当前包关系、子系统地图、最小接入路径与 `docs/zh-CN` 入口
|
||||
- `GFramework.Godot.SourceGenerators/README.md` 没有覆盖 `AutoScene`、`AutoUiPage`、`AutoRegisterExportedCollections` 这些当前已发布的生成器分组
|
||||
- `docs/zh-CN/api-reference/index.md` 的 `Godot` 映射仍只把生成器入口落到泛化总览页，恢复效率偏低
|
||||
- 因此本轮执行最小修复集：
|
||||
- 重写 `GFramework.Godot/README.md`
|
||||
- 重写 `GFramework.Godot.SourceGenerators/README.md`
|
||||
- 更新 `docs/zh-CN/api-reference/index.md` 的 `Godot` 行
|
||||
|
||||
### 当前决策（RP-011）
|
||||
|
||||
- 这轮不改 `docs/zh-CN/godot/**` landing / topic 页面，因为站内页面本身没有发现新的事实漂移，问题集中在仓库 README 与 API 入口的回退
|
||||
- `GFramework.Godot` README 必须和 `Game` / `Godot` 真实边界一致，明确它不是生成器 owner，也不引入虚构的 router 类型
|
||||
- `GFramework.Godot.SourceGenerators` README 采用“元数据 / 节点注入与信号绑定 / 行为包装 / 批量注册”四段式入口，避免读者只看到旧的三项能力
|
||||
- API 参考页对 `Godot` 生成器入口直接给出专题页链接，而不是仅要求读者再从总览页二次分流
|
||||
|
||||
### 当前验证（RP-011）
|
||||
|
||||
- 模块扫描：
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`：通过
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot.SourceGenerators`：通过
|
||||
- 文档校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot/README.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot.SourceGenerators/README.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot.SourceGenerators/README.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 继续抽查根 `README.md`、`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 是否仍把 `Godot` owner 写回旧边界
|
||||
2. 当后续分支继续修改 `Game` / `Godot` family 入口时，沿用当前 README -> landing -> API reference 的最小修复顺序
|
||||
|
||||
### 当前恢复点：RP-012
|
||||
|
||||
- 继续按 `boot` 恢复后的默认下一步执行 `Game` / `Godot` 入口巡检，并重新读取：
|
||||
- `README.md`
|
||||
- `docs/zh-CN/source-generators/index.md`
|
||||
- `docs/zh-CN/tutorials/godot-integration.md`
|
||||
- `docs/zh-CN/api-reference/index.md`
|
||||
- `GFramework.Godot/README.md`
|
||||
- `GFramework.Godot.SourceGenerators/README.md`
|
||||
- 巡检结果显示主体内容仍然稳定，但根入口摘要存在一处残留漂移：
|
||||
- 根 `README.md` 仍把 `GFramework.Godot.SourceGenerators` 写成“Godot 场景专用源码生成器”，与当前包实际覆盖的 `project.godot` 元数据、节点注入、信号绑定、Scene / UI 包装和导出集合注册职责不符
|
||||
- `docs/zh-CN/source-generators/index.md` 的选包描述同步缺少 Scene / UI 包装与导出集合注册辅助这组能力
|
||||
- 因此本轮执行最小修复集：
|
||||
- 更新根 `README.md` 的 `GFramework.Godot.SourceGenerators` 模块描述
|
||||
- 更新 `docs/zh-CN/source-generators/index.md` 的 Godot 选包摘要
|
||||
|
||||
### 当前决策（RP-012）
|
||||
|
||||
- 继续维持“只修新发现的入口漂移，不重写稳定页面”的治理节奏；这轮不改 `docs/zh-CN/tutorials/godot-integration.md`，因为教程与 README / 生成器专题页仍使用同一套职责边界
|
||||
- 根 `README.md` 作为仓库一级入口，必须与模块 README 保持同一粒度的职责摘要；如果根入口比模块 README 更旧，后续 `boot` 和人工恢复都会被误导
|
||||
- `source-generators/index.md` 的选包段落需要覆盖当前真实能力分组，但不重复展开各专题页细节，避免重新长成第二份 README
|
||||
|
||||
### 当前验证（RP-012）
|
||||
|
||||
- 文档校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh README.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 继续抽查 `docs/zh-CN/tutorials/godot-integration.md`、`docs/zh-CN/godot/index.md` 与根 `README.md` 的职责摘要是否继续保持同一口径
|
||||
2. 当后续分支继续修改 `Game` / `Godot` family 入口时，沿用当前 README -> landing -> API reference 的最小修复顺序
|
||||
|
||||
### 当前恢复点：RP-013
|
||||
|
||||
- 使用 `$gframework-boot` 恢复当前 worktree 后，按 `documentation-full-coverage-governance` 的默认下一步执行一次
|
||||
validation-only 巡检，并补读：
|
||||
- `README.md`
|
||||
- `docs/zh-CN/godot/index.md`
|
||||
- `docs/zh-CN/tutorials/godot-integration.md`
|
||||
- `docs/zh-CN/source-generators/index.md`
|
||||
- `docs/zh-CN/api-reference/index.md`
|
||||
- `GFramework.Godot/README.md`
|
||||
- `.agents/skills/gframework-doc-refresh/SKILL.md`
|
||||
- 同时执行 `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`，确认当前 `Godot`
|
||||
docs surface 除 `index.md`、`architecture.md`、`scene.md`、`ui.md`、`signal.md`、`extensions.md`、`logging.md`
|
||||
外，还应把 `storage.md` 与 `setting.md` 视为默认恢复集合的一部分
|
||||
- 巡检结论：
|
||||
- 根 `README.md`、`docs/zh-CN/godot/index.md`、`docs/zh-CN/tutorials/godot-integration.md`、
|
||||
`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/api-reference/index.md` 当前仍保持同一套 `Godot`
|
||||
owner / adoption path 叙述，没有发现新的入口漂移
|
||||
- 本轮不需要改动稳定的 README / docs 页面，只需要把 active topic 的最小恢复摘要补齐到当前 landing page
|
||||
实际覆盖的页集合
|
||||
- 因此本轮执行的唯一修改是：
|
||||
- 更新 `ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md`
|
||||
的恢复点、`Godot` 页面集合、稳定性巡检结论与下一步
|
||||
- 记录本条 `RP-013` trace，保证未来 `boot` 不会漏掉 `storage.md` / `setting.md`
|
||||
|
||||
### 当前决策（RP-013）
|
||||
|
||||
- 当前 topic 继续保持“巡检优先、最小修复”的节奏；验证通过时不为凑改动而重写稳定页面
|
||||
- `scan_module_evidence.py` 识别出的 docs surface 应优先反映到 active recovery artifact，而不是只留在一次性 chat
|
||||
上下文
|
||||
- `Godot` family 的后续巡检重点从“根入口是否还残留旧描述”切换为“storage / setting 子页是否和 landing / README
|
||||
保持同一口径”
|
||||
|
||||
### 当前验证（RP-013）
|
||||
|
||||
- 模块扫描：
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`：通过
|
||||
- 文档校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 若后续分支继续调整 `GFramework.Godot` 运行时入口，优先复核 `docs/zh-CN/godot/storage.md`、`setting.md` 与根
|
||||
`README.md` / landing page 是否仍保持同一套职责边界
|
||||
2. 当后续分支再修改 `Godot` / `Game` family 的 README、docs 或公共 API 时，回到对应模块追加 targeted 巡检与验证
|
||||
|
||||
### 当前恢复点：RP-016
|
||||
|
||||
- 用户明确要求“继续下一步的文档治理，并形成足够体量的 PR”后，当前 topic 不再停留在 validation-only 巡检，
|
||||
而是切到一个可独立成波次的 `Game` persistence docs surface：
|
||||
- `docs/zh-CN/game/data.md`
|
||||
- `docs/zh-CN/game/storage.md`
|
||||
- `docs/zh-CN/game/serialization.md`
|
||||
- `docs/zh-CN/game/setting.md`
|
||||
- 先执行 `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`，确认 `Game` 的默认 docs surface
|
||||
包含 `data`、`storage`、`serialization`、`setting`、`scene`、`ui`、`config-system` 与 landing / API fallback
|
||||
- 结合 `GFramework.Game/README.md`、`FileStorage.cs`、`ScopedStorage.cs`、`DataRepository.cs`、
|
||||
`UnifiedSettingsDataRepository.cs`、`SaveRepository.cs`、`JsonSerializer.cs`、`SettingsModel.cs`、
|
||||
`SettingsSystem.cs`、`JsonSerializerTests.cs`、`SettingsModelTests.cs` 与 `PersistenceTests.cs`，确认四个旧页面存在持续性漂移：
|
||||
- `storage.md` 仍按旧版通用 API 手册组织，没有强调 `FileStorage` / `ScopedStorage` 与 repository 的职责边界
|
||||
- `data.md` 缺少 `DataRepository`、`UnifiedSettingsDataRepository` 与 `SaveRepository<TSaveData>` 三层分工，以及当前备份 /
|
||||
批量事件 / 存档迁移语义
|
||||
- `serialization.md` 仍沿用“业务层手工 Serialize 再写回 storage”的旧接法，没有反映当前 `FileStorage`
|
||||
已直接复用注入的 `ISerializer`
|
||||
- `setting.md` 虽已回到 `ISettingsModel` / `RegisterApplicator(...)` 口径，但结构仍未与当前 `Game` family 的 runtime topic
|
||||
页面统一，也缺少 frontmatter
|
||||
- 因此本轮执行的最小但成组修复集是：
|
||||
- 重写 `docs/zh-CN/game/storage.md`
|
||||
- 重写 `docs/zh-CN/game/data.md`
|
||||
- 重写 `docs/zh-CN/game/serialization.md`
|
||||
- 重写 `docs/zh-CN/game/setting.md`
|
||||
- 更新 active tracking 的恢复点、治理结论与下一步
|
||||
|
||||
### 当前决策（RP-016）
|
||||
|
||||
- 这轮不去扩张到 `Game` tutorial 或 root README，而是把同一子领域里仍残留的旧页一次性收口，形成清晰的 PR 边界
|
||||
- `Game` persistence docs surface 统一采用“当前公开入口 -> 最小接入路径 -> 当前边界 -> 继续阅读”的结构，
|
||||
不再维护分散的伪 API 手册页
|
||||
- 文档示例只保留可直接映射到当前框架类型、测试行为或已验证 consumer wiring 的内容，避免继续写虚构接线名
|
||||
|
||||
### 当前验证（RP-016）
|
||||
|
||||
- 模块扫描：
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`：通过
|
||||
- 文档校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/serialization.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/setting.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
- 代码 / 测试证据：
|
||||
- `GFramework.Game/README.md`
|
||||
- `GFramework.Game/Storage/FileStorage.cs`
|
||||
- `GFramework.Game/Storage/ScopedStorage.cs`
|
||||
- `GFramework.Game/Data/DataRepository.cs`
|
||||
- `GFramework.Game/Data/UnifiedSettingsDataRepository.cs`
|
||||
- `GFramework.Game/Data/SaveRepository.cs`
|
||||
- `GFramework.Game/Serializer/JsonSerializer.cs`
|
||||
- `GFramework.Game/Setting/SettingsModel.cs`
|
||||
- `GFramework.Game/Setting/SettingsSystem.cs`
|
||||
- `GFramework.Game.Tests/Data/PersistenceTests.cs`
|
||||
- `GFramework.Game.Tests/Serializer/JsonSerializerTests.cs`
|
||||
- `GFramework.Game.Tests/Setting/SettingsModelTests.cs`
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 回填 tracking 的最新验证结果，并按仓库规则提交本轮 `Game` persistence docs wave
|
||||
2. 若后续分支继续调整 `GFramework.Game` 的 persistence runtime 或 README，优先复核这四个 topic page 与 landing page 的一致性
|
||||
|
||||
### 当前恢复点：RP-015
|
||||
|
||||
- 通过 `$gframework-boot` 恢复当前 worktree 后，继续按 `documentation-full-coverage-governance` 的默认下一步执行一次
|
||||
validation-only 巡检，并补读：
|
||||
- `GFramework.Godot/README.md`
|
||||
- `docs/zh-CN/godot/index.md`
|
||||
- `docs/zh-CN/godot/storage.md`
|
||||
- `docs/zh-CN/godot/setting.md`
|
||||
- `docs/zh-CN/source-generators/index.md`
|
||||
- `docs/zh-CN/api-reference/index.md`
|
||||
- `docs/zh-CN/tutorials/godot-integration.md`
|
||||
- `GFramework.Godot/Setting/GodotAudioSettings.cs`
|
||||
- `GFramework.Godot/Setting/GodotGraphicsSettings.cs`
|
||||
- `GFramework.Godot/Setting/GodotLocalizationSettings.cs`
|
||||
- `GFramework.Game.Tests/Setting/GodotLocalizationSettingsTests.cs`
|
||||
- 同时重新执行 `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`，确认 `Godot`
|
||||
docs surface 仍然覆盖 landing、`storage.md`、`setting.md`、source-generators fallback、API reference 与
|
||||
CoreGrid 参考接线，没有新的默认恢复页缺口
|
||||
- 巡检结论：
|
||||
- `GFramework.Godot/README.md`、`docs/zh-CN/godot/index.md`、`storage.md`、`setting.md`、`docs/zh-CN/source-generators/index.md`、
|
||||
`docs/zh-CN/api-reference/index.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 当前仍保持同一套
|
||||
`Godot` owner / adoption path 叙述，没有发现自 `RP-014` 之后的新入口漂移
|
||||
- `setting.md` 里关于 `ISettingsModel`、`RegisterApplicator(...)`、`LocalizationMap` fallback 的描述，仍与
|
||||
`GodotAudioSettings`、`GodotGraphicsSettings`、`GodotLocalizationSettings` 以及
|
||||
`GodotLocalizationSettingsTests` 保持一致
|
||||
- 因此本轮执行的唯一修改是：
|
||||
- 更新 active tracking 与 trace 的恢复点、巡检结论和验证结果
|
||||
|
||||
### 当前决策（RP-015）
|
||||
|
||||
- 当前 topic 继续维持“巡检优先、无漂移则只更新 recovery artifact”的治理节奏，不为凑改动重写稳定页面
|
||||
- `boot` 恢复本身也应留下可复用的恢复证据，避免下一次启动时重复判断“最近一次巡检是否已经覆盖 `storage.md` /
|
||||
`setting.md`”
|
||||
|
||||
### 当前验证（RP-015）
|
||||
|
||||
- 模块扫描：
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`：通过
|
||||
- 文档校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 若后续分支继续调整 `GFramework.Godot` 运行时入口，优先复核 `docs/zh-CN/godot/storage.md`、`setting.md` 与根
|
||||
`README.md` / landing page 是否仍保持同一套职责边界
|
||||
2. 当后续分支再修改 `Godot` / `Game` family 的 README、docs 或公共 API 时，回到对应模块追加 targeted 巡检与验证
|
||||
|
||||
### 当前恢复点：RP-014
|
||||
|
||||
- 继续沿用 `RP-013` 的 `Godot` docs surface 巡检范围，补读：
|
||||
- `docs/zh-CN/godot/storage.md`
|
||||
- `docs/zh-CN/godot/setting.md`
|
||||
- `GFramework.Godot/Storage/GodotFileStorage.cs`
|
||||
- `GFramework.Godot/Setting/GodotAudioSettings.cs`
|
||||
- `GFramework.Godot/Setting/GodotGraphicsSettings.cs`
|
||||
- `GFramework.Godot/Setting/GodotLocalizationSettings.cs`
|
||||
- `GFramework.Godot/Setting/Data/AudioBusMap.cs`
|
||||
- `GFramework.Godot/Setting/Data/LocalizationMap.cs`
|
||||
- `GFramework.Game.Tests/Setting/GodotLocalizationSettingsTests.cs`
|
||||
- `ai-libs/CoreGrid/scripts/module/UtilityModule.cs`
|
||||
- `ai-libs/CoreGrid/scripts/module/ModelModule.cs`
|
||||
- 巡检发现两处新的 topic 级漂移：
|
||||
- `docs/zh-CN/godot/storage.md` 仍按旧版 API 手册组织，缺少 frontmatter、当前 `IStorage` / repository 分工与
|
||||
`GodotYamlConfigLoader` 分流说明
|
||||
- `docs/zh-CN/godot/setting.md` 仍使用过时的“settings data 直接注入 applicator 构造函数”叙述，没有反映当前
|
||||
`ISettingsModel` + `RegisterApplicator(...)` 的真实接线方式
|
||||
- 因此本轮执行最小修复集：
|
||||
- 重写 `docs/zh-CN/godot/storage.md`
|
||||
- 重写 `docs/zh-CN/godot/setting.md`
|
||||
- 更新 active tracking 的恢复点、巡检结论与验证结果
|
||||
|
||||
### 当前决策（RP-014）
|
||||
|
||||
- 继续遵循“README / landing 稳定时，不重写稳定入口；只修新发现的 topic 漂移”的治理节奏
|
||||
- `storage.md` 应强调宿主路径语义与 repository 分工，而不是重复 `Game` 通用存储手册
|
||||
- `setting.md` 应强调 applicator 注册和运行时边界，而不是重新维护一份过时的设置 API 摘要
|
||||
|
||||
### 当前验证（RP-014）
|
||||
|
||||
- 模块扫描：
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`：通过
|
||||
- 文档校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 若后续分支继续调整 `GFramework.Godot` 运行时入口，优先复核 `docs/zh-CN/godot/storage.md`、`setting.md` 与根
|
||||
`README.md` / landing page 是否仍保持同一套职责边界
|
||||
2. 当后续分支再修改 `Godot` / `Game` family 的 README、docs 或公共 API 时，回到对应模块追加 targeted 巡检与验证
|
||||
1. 如果 PR `#272` 的 `Title check` 仍需要处理，到 GitHub 上把标题改成更具体的文档治理描述。
|
||||
2. 若后续分支继续调整 `Game` persistence runtime 或 README，优先复核 `docs/zh-CN/game/data.md`、
|
||||
`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持一致。
|
||||
3. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
|
||||
`docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。
|
||||
|
||||
@ -49,6 +49,21 @@ description: 以当前 GFramework.Game 源码与 PersistenceTests 为准，说
|
||||
- 保存、删除时会整文件回写，而不是只改单个 section 文件
|
||||
- 开启 `AutoBackup` 时，备份粒度也是整个统一文件，不是单个 section
|
||||
|
||||
当 `DataRepositoryOptions.BasePath = "settings"`，并保持默认文件名时，最小目录结构通常是：
|
||||
|
||||
```text
|
||||
settings/
|
||||
settings.json
|
||||
```
|
||||
|
||||
如果同时开启 `AutoBackup = true`，则同一路径下还会额外出现：
|
||||
|
||||
```text
|
||||
settings/
|
||||
settings.json
|
||||
settings.backup
|
||||
```
|
||||
|
||||
### `SaveRepository<TSaveData>`
|
||||
|
||||
适合：
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user