diff --git a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md index ec215718..578662a2 100644 --- a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md +++ b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md @@ -12,7 +12,7 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-018` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-019` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述 @@ -31,11 +31,11 @@ - 为 `docs/zh-CN/game/data.md` 补充 `UnifiedSettingsDataRepository` 的统一文件布局示例 - 为 `GFramework.Godot.SourceGenerators/README.md` 补充手写 `_Ready()` / `_ExitTree()` 时显式调用生成方法的最小样例 - 将过长的 active tracking / trace 瘦身，并把历史摘要迁回 `archive/` -- `2026-04-23` 使用 `$gframework-pr-review` 重新抓取 PR `#272` 后，确认最新 latest-head review 里仍有 1 条 - Greptile open thread，指出 `GFramework.Godot.SourceGenerators/README.md` 的最小样例误写成 - `using GFramework.Godot.Attribute;`。 -- 该命名空间错误已在本地修正为 `using GFramework.Godot.SourceGenerators.Abstractions;`，待提交并推送后再回到 - GitHub 侧确认 open thread 是否消失。 +- `2026-04-23` 使用 `$gframework-pr-review` 重新抓取 PR `#272` 后，确认 latest-head review 当前仍有 1 条 + Greptile open thread，定位到 `docs/zh-CN/godot/setting.md:75` 的 inline code 误写成 + `SettingsModel<ISettingsDataRepository>`。 +- 结合当前 PR 已改动的 `docs/zh-CN/godot/storage.md` 做同类巡检后，确认 `SaveRepository<TSaveData>` + 也会在 VitePress code span 中按字面量渲染；两处现已在本地统一改为真实泛型写法。 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地 文件缺陷。 @@ -57,20 +57,18 @@ ## 最新验证 -- `2026-04-23` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` +- `2026-04-23` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json` - 结果：通过；PR `#272` 处于 `OPEN`，latest head commit 存在 1 条 Greptile open thread，定位到 - `GFramework.Godot.SourceGenerators/README.md:135` 的错误命名空间引用。 -- `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` - - 结果：通过。 + `docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。 +- `2026-04-23` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' GFramework.Godot.SourceGenerators/README.md GFramework.Godot/README.md README.md docs/zh-CN/api-reference/index.md docs/zh-CN/game/data.md docs/zh-CN/game/serialization.md docs/zh-CN/game/setting.md docs/zh-CN/game/storage.md docs/zh-CN/godot/setting.md docs/zh-CN/godot/storage.md docs/zh-CN/source-generators/index.md` + - 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。 - `2026-04-23` `bun run build`（工作目录：`docs/`） - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。 ## 下一步 -1. 提交并推送本地对 `GFramework.Godot.SourceGenerators/README.md` 的命名空间修正，然后重新抓取 PR `#272` - 确认 Greptile open thread 是否消失。 +1. 提交并推送本地对 `docs/zh-CN/godot/setting.md` 与 `docs/zh-CN/godot/storage.md` 的 Markdown 泛型写法修正， + 然后重新抓取 PR `#272` 确认 Greptile open thread 是否已在新 head commit 上消失。 2. 如果 PR `#272` 的 `Title check` 仍需要消除，到 GitHub 上把标题改成更具体的文档治理描述。 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 diff --git a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md index 727e323c..fb3c5093 100644 --- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -2,46 +2,49 @@ ## 2026-04-23 -### 当前恢复点：RP-018 +### 当前恢复点：RP-019 - 使用 `$gframework-pr-review` 重新复核当前分支 PR `#272`。 - GitHub latest-head review 当前暴露 1 条新的 Greptile open thread： - `GFramework.Godot.SourceGenerators/README.md:135` 把示例命名空间写成了不存在的 - `GFramework.Godot.Attribute`。 -- 本地核对源码与现有文档后，确认 `[GetNode]` / `[BindNodeSignal]` 应来自 - `GFramework.Godot.SourceGenerators.Abstractions`，该评论成立。 + `docs/zh-CN/godot/setting.md:75` 在 inline code 中写成 + `SettingsModel<ISettingsDataRepository>`。 +- 本地核对当前文档渲染语义后，确认 CommonMark / VitePress 不会在 code span 内解码 HTML entity， + 该评论成立。 +- 对当前 PR 已变更的 Godot 文档做同类扫描后，又在 `docs/zh-CN/godot/storage.md:102` 发现 + `SaveRepository<TSaveData>` 的同型问题。 - 本轮执行的修复： - - 将 `GFramework.Godot.SourceGenerators/README.md` 的示例 using 改为 - `GFramework.Godot.SourceGenerators.Abstractions` + - 将 `docs/zh-CN/godot/setting.md` 的 `SettingsModel<ISettingsDataRepository>` 改为 + `SettingsModel` + - 将 `docs/zh-CN/godot/storage.md` 的 `SaveRepository<TSaveData>` 改为 + `SaveRepository` - 同步更新 active tracking / trace，记录该 PR review follow-up 与新的恢复点 -### 当前决策（RP-018） +### 当前决策（RP-019） - PR review 结果以 GitHub latest-head open threads 为准；即便 active tracking 曾记录“无 open thread”，也必须按新抓取结果回写。 -- 对 `GFramework.Godot.SourceGenerators/README.md` 这类模块 README，最小代码样例的命名空间必须与源码中的 - `Abstractions` 包保持一致，不能沿用历史别名或猜测命名。 +- 对 Markdown inline code 中的 C# 泛型示例，必须直接写真实的 `` 语法，不能在反引号内部再写 + `<` / `>`，否则 VitePress 会把 entity 当作字面量展示。 +- 当 latest-head review 命中某个文档表述问题时，应顺手扫描同一批 PR 已改动文档中的同类模式，避免只消掉单条 thread 却把相同渲染缺陷留在相邻页面。 - 当前本地修复完成后，下一次 GitHub 侧复核需要基于新提交/新 head commit，而不是旧的 PR review 快照。 -### 当前验证（RP-018） +### 当前验证（RP-019） - PR review 抓取： - - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json` - 结果：通过；PR `#272` 处于 `OPEN`，latest head commit 存在 1 条 Greptile open thread，定位到 - `GFramework.Godot.SourceGenerators/README.md:135` 的错误命名空间引用。 -- 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` - - 结果：通过。 + `docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。 +- 同类模式巡检： + - `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' GFramework.Godot.SourceGenerators/README.md GFramework.Godot/README.md README.md docs/zh-CN/api-reference/index.md docs/zh-CN/game/data.md docs/zh-CN/game/serialization.md docs/zh-CN/game/setting.md docs/zh-CN/game/storage.md docs/zh-CN/godot/setting.md docs/zh-CN/godot/storage.md docs/zh-CN/source-generators/index.md` + - 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。 - 构建校验： - `bun run build`（工作目录：`docs/`） - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。 -### 归档摘要（RP-017） +### 归档摘要（RP-018） -- active recovery artifact 只保留当前恢复点、当前事实、风险、验证结果与下一步；旧阶段细节统一转移到 archive。 -- `Game` persistence docs surface 继续以 `data.md`、`storage.md`、`serialization.md`、`setting.md` 作为最小巡检集合。 -- `GFramework.Godot.SourceGenerators/README.md` 的生命周期接法说明应直接复用与 tutorial 一致的最小样例，避免 README 与教程再次分叉。 +- 使用 `$gframework-pr-review` 重新复核当前分支 PR `#272`。 +- latest-head review 命中 `GFramework.Godot.SourceGenerators/README.md:135` 的错误命名空间引用，并已在本地修正。 +- README 校验与 `docs/` 站点构建通过，待新提交推送后回 GitHub 侧确认 open thread 消失。 ### 归档指针 diff --git a/docs/zh-CN/godot/setting.md b/docs/zh-CN/godot/setting.md index 9104cd20..84091c8f 100644 --- a/docs/zh-CN/godot/setting.md +++ b/docs/zh-CN/godot/setting.md @@ -72,7 +72,7 @@ description: 以当前 GFramework.Godot 源码、测试与 CoreGrid 接线为准 ## 最小接入路径 -当前消费者 `ai-libs/CoreGrid` 的接法，是先注册 `SettingsModel<ISettingsDataRepository>`，再把 Godot applicator +当前消费者 `ai-libs/CoreGrid` 的接法，是先注册 `SettingsModel`，再把 Godot applicator 挂进去： ```csharp diff --git a/docs/zh-CN/godot/storage.md b/docs/zh-CN/godot/storage.md index 0ac1d2da..7ad94a59 100644 --- a/docs/zh-CN/godot/storage.md +++ b/docs/zh-CN/godot/storage.md @@ -99,7 +99,7 @@ architecture.RegisterUtility>(new SaveRepository 文件读写 - `UnifiedSettingsDataRepository` 负责设置节聚合与持久化 -- `SaveRepository<TSaveData>` 负责存档结构和保存槽位语义 +- `SaveRepository` 负责存档结构和保存槽位语义 不要把 `GodotFileStorage` 本身写成“设置系统”或“存档系统”的 owner。