mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
docs(pr-review): 收口文档评审遗留问题
- 更新 active tracking / trace 为当前恢复入口，并归档 RP-023 到 RP-025 的阶段细节 - 修复 zh-CN context 页面标题本地化与 troubleshooting 绝对链接后缀不一致问题 - 补充 PR #282 follow-up 的验证记录并确认 docs 站点构建通过
This commit is contained in:
gewuyou
parent
982249151e
commit
5b9c879320
@ -0,0 +1,133 @@
|
||||
# Documentation Full Coverage Governance Status History RP-023 To RP-025
|
||||
|
||||
以下内容从 active tracking 中迁出，用于保留 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-023` 到
|
||||
`DOCUMENTATION-FULL-COVERAGE-GOV-RP-025` 的批处理状态、验证细节与恢复背景。默认 `boot` 只需要读取 active
|
||||
tracking 中的最新摘要；若需要追溯 `2026-04-23` 到 `2026-04-24` 的治理细节，再回到本归档文件。
|
||||
|
||||
## 迁出的状态摘要
|
||||
|
||||
- `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/`
|
||||
- `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 中按字面量渲染；两处现已在本地统一改为真实泛型写法。
|
||||
- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对
|
||||
`README.md`、`GFramework.*` 与 `docs/zh-CN/**` 执行同类模式巡检，确认剩余热点仅位于
|
||||
`docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处。
|
||||
- 上述 8 处 inline code 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 已统一改为真实
|
||||
泛型写法，避免在 VitePress 中显示字面量 HTML entity。
|
||||
- `2026-04-23` 根据本轮使用反馈，已为 `.agents/skills/gframework-batch-boot/SKILL.md` 与
|
||||
`.agents/skills/README.md` 补充数字速记阈值语义：
|
||||
- `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止”
|
||||
- `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止”
|
||||
- `75 | 2000` 仅作为可理解的 OR 写法保留，不再作为推荐写法，以避免与 shell pipe 混淆
|
||||
- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对
|
||||
`docs/zh-CN/getting-started/index.md`、`core/index.md`、`game/index.md`、`source-generators/index.md`、
|
||||
`api-reference/index.md`、`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`
|
||||
做导航可达性修复，把仓库 README / 根 README 裸路径统一改为指向 GitHub `main` 分支的可点击链接。
|
||||
- 该批次不改变文档语义，只收口 docs 站点中的入口可达性；适合继续作为小步快跑的低风险治理模式。
|
||||
- `2026-04-23` 在同一基线下继续收口第二批专题页导航热点，已将 `core/cqrs.md`、`ecs/arch.md`、
|
||||
`abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 和 6 个
|
||||
`source-generators/*.md` 专题页里的 README 裸路径统一改为 GitHub `main` blob 外链。
|
||||
- 截至提交 `8a11720`（`2026-04-23T21:01:28+08:00`），当前分支相对 `origin/main`（`aa879d2`）的累计 diff
|
||||
为 `24` 个文件、`264` 行，仍低于 `$gframework-batch-boot 75` 的停止阈值；但剩余命中已主要是正文语义性提及，不再适合作为同类批处理。
|
||||
- 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地
|
||||
文件缺陷。
|
||||
- `2026-04-24` 根据用户反馈完成一轮“公开文档边界”治理，并继续按 `$gframework-batch-boot 75` 向前推进：
|
||||
- 在 `AGENTS.md`、`.agents/skills/_shared/DOCUMENTATION_STANDARDS.md` 与
|
||||
`.agents/skills/gframework-doc-refresh/SKILL.md` 中新增硬约束，明确禁止把 inventory、覆盖基线、恢复点、
|
||||
review backlog、治理批次等 contributor-only 内容写进 `README.md` 与 `docs/**`
|
||||
- 将 `docs/zh-CN/core/index.md`、`core/cqrs.md`、`game/index.md`、
|
||||
`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`、`ecs/index.md`、
|
||||
`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md` 中的 XML 覆盖表述改写为面向读者的“源码阅读入口”
|
||||
- 顺手收口 `api-reference/index.md`、`contributor/development-environment.md` 与
|
||||
`source-generators/*.md` 中的内部口吻用语，例如 `landing page`、`验证基线`、`目标类型基线`
|
||||
- focused validator 已覆盖本轮触达的 `13` 个公开文档页面并全部通过；站点构建 `cd docs && bun run build`
|
||||
已通过，仅保留既有大 chunk warning
|
||||
- 当前分支 `HEAD` 仍与 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）对齐；在提交本轮工作前，
|
||||
工作树待提交范围为 `16` 个文件、`224` changed lines，距离 `$gframework-batch-boot 75` 的停止阈值仍很远。
|
||||
- `2026-04-24` 继续在同一 stop condition 下执行第二个低风险批次，集中修复 `docs/zh-CN/core/*.md` 的历史 frontmatter 缺口：
|
||||
- 已为 `architecture.md`、`async-initialization.md`、`command.md`、`configuration.md`、`context.md`、
|
||||
`environment.md`、`events.md`、`extensions.md`、`functional.md`、`ioc.md`、`localization.md`、
|
||||
`logging.md`、`model.md`、`pause.md`、`pool.md`、`property.md`、`query.md`、`rule.md`、
|
||||
`state-management.md`、`system.md`、`utility.md` 补齐 frontmatter
|
||||
- 顺手修复 `core/ioc.md` 的 `xref:System.Threading.ReaderWriterLockSlim` 坏链，以及
|
||||
`core/state-management.md` 中 4 处缺少 `.md` 后缀的站内链接
|
||||
- 当前 `docs/zh-CN/core/*.md` 已全部具备 frontmatter；focused validator 对这 `21` 个页面全部通过，`bun run build`
|
||||
再次通过，仅保留既有大 chunk warning
|
||||
- 截至当前未提交工作树，`HEAD` 相对 `origin/main` 的累计 branch diff 仍为 `18` 个文件；新增待提交批次为 `21` 个文件、
|
||||
`126` changed lines，合并后仍显著低于 `$gframework-batch-boot 75` 的停止阈值。
|
||||
- `2026-04-24` 继续在同一 stop condition 下执行第三个低风险批次，集中清理 `docs/zh-CN` 其余“完全缺 frontmatter”的页面：
|
||||
- 已为 `best-practices/*.md` 中缺口页、`contributing.md`、`faq.md`、`game/config-system.md`、
|
||||
`getting-started/*.md`、`godot/coroutine.md`、6 个 `source-generators/*.md`、`troubleshooting.md`、
|
||||
`tutorials/advanced-patterns.md`、`tutorials/basic/index.md` 与 `tutorials/index.md` 补齐 frontmatter
|
||||
- 在同批次内修复 `best-practices/multiplayer.md` 的未闭合代码块、`source-generators/*.md` 中缺少 `.md`
|
||||
后缀的相对链接，以及 `troubleshooting.md` 里 3 处目录索引死链
|
||||
- 当前 `docs/zh-CN` 已不存在“完全缺 frontmatter”的页面；剩余 metadata 热点只剩
|
||||
`docs/zh-CN/index.md` 与 `docs/zh-CN/tutorials/basic/01-07.md` 共 `8` 个“已有 frontmatter 但缺 title /
|
||||
description”的页面
|
||||
- 本批次落地前，当前分支相对 `origin/main` 的累计 branch diff 为 `39` 个文件；连同本轮工作和 tracking / trace
|
||||
更新后，预计提交后累计 diff 约为 `63` 个文件，仍低于 `$gframework-batch-boot 75` 的停止阈值
|
||||
|
||||
## 迁出的验证记录
|
||||
|
||||
- `2026-04-24` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
|
||||
- 结果：失败；暴露出仓库既有的 `53` 个历史文档问题（大量缺少 frontmatter、既有坏链与未标语言代码块），不由本轮改动引入，因此本轮改用 focused validator 证明任务级结果。
|
||||
- `2026-04-24` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
|
||||
- 结果：通过；确认 `Core` 模块的 README、landing、topic 与 fallback docs 入口仍可解析。
|
||||
- `2026-04-24` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`
|
||||
- 结果：通过；确认 `Game` 模块的 README、landing、topic 与 fallback docs 入口仍可解析。
|
||||
- `2026-04-24` focused validator（逐个校验本轮触达页面）
|
||||
- 结果：通过；`docs/zh-CN/abstractions/core-abstractions.md`、
|
||||
`abstractions/ecs-arch-abstractions.md`、`abstractions/game-abstractions.md`、
|
||||
`api-reference/index.md`、`contributor/development-environment.md`、`core/cqrs.md`、`core/index.md`、
|
||||
`ecs/arch.md`、`ecs/index.md`、`game/index.md`、
|
||||
`source-generators/bind-node-signal-generator.md`、
|
||||
`source-generators/cqrs-handler-registry-generator.md`、
|
||||
`source-generators/get-node-generator.md` 的 frontmatter / links / code blocks 全部通过。
|
||||
- `2026-04-24` `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；仅保留既有大 chunk warning。
|
||||
- `2026-04-24` `python3 - <<'PY' ...`（检查 `docs/zh-CN/core/*.md` frontmatter）
|
||||
- 结果：通过；`docs/zh-CN/core/` 当前所有 Markdown 页面均已带 frontmatter。
|
||||
- `2026-04-24` focused validator（逐个校验 `docs/zh-CN/core/*.md` 的 `21` 个页面）
|
||||
- 结果：通过；过程中暴露并已修复 `core/ioc.md` 的 `ReaderWriterLockSlim` 坏链与
|
||||
`core/state-management.md` 的 4 处站内坏链；剩余仅为既有代码块语言 warning，不影响任务级通过。
|
||||
- `2026-04-24` `bun run build`（工作目录：`docs/`，第二次）
|
||||
- 结果：通过；frontmatter 与坏链修复后站点仍可正常构建，仅保留既有大 chunk warning。
|
||||
- `2026-04-24` focused validator（逐个校验第三批触达的 `22` 个页面）
|
||||
- 结果：通过；frontmatter、真实坏链与未闭合代码块问题均已修复，剩余仅为 `best-practices/architecture-patterns.md`、
|
||||
`best-practices/index.md`、`contributing.md`、`troubleshooting.md` 与 `tutorials/index.md` 的既有代码块语言 warning。
|
||||
- `2026-04-24` `bun run build`（工作目录：`docs/`，第三次）
|
||||
- 结果：通过；第三批 frontmatter 与链接修复后站点仍可正常构建，仅保留既有大 chunk warning。
|
||||
- `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，定位到
|
||||
`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` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'`
|
||||
- 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。
|
||||
- `2026-04-23` `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md` 与 `sed -n '1,220p' .agents/skills/README.md`
|
||||
- 结果：确认原文仅描述自然语言 stop condition，没有定义数字速记或多阈值 OR 语义；现已补齐。
|
||||
- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
|
||||
- 结果：确认 landing / API 导航页仍有一批裸路径仓库入口；本轮已先修复 `getting-started`、`core`、`game`、
|
||||
`source-generators`、`api-reference` 与两个 abstractions 页面。
|
||||
- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
|
||||
- 结果：定位第二批专题页导航热点，已修复 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、
|
||||
`game/scene.md`、`game/ui.md` 以及 6 个 `source-generators/*.md` 页面。
|
||||
- `2026-04-23` `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；仓库 README 外链改为 GitHub `main` blob 后，不再触发 VitePress dead link；仅保留既有大 chunk warning。
|
||||
|
||||
## 迁出的下一步
|
||||
|
||||
1. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8`
|
||||
个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。
|
||||
2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖
|
||||
常见分支阈值场景。
|
||||
3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
|
||||
`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
|
||||
4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
|
||||
`docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。
|
||||
@ -0,0 +1,167 @@
|
||||
# Documentation Full Coverage Governance Trace History RP-023 To RP-025
|
||||
|
||||
以下内容从 active trace 中迁出，用于保留 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-023` 到
|
||||
`DOCUMENTATION-FULL-COVERAGE-GOV-RP-025` 的执行时间线、关键决策与主要验证结果。默认 `boot` 只需要读取
|
||||
active trace 中的最新恢复点；若需要追溯 `2026-04-23` 到 `2026-04-24` 的批处理执行顺序，再回到本归档文件。
|
||||
|
||||
## 2026-04-24
|
||||
|
||||
### 当前恢复点：RP-025
|
||||
|
||||
- 继续沿用 `$gframework-batch-boot 75`，基线保持 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）。
|
||||
- 本轮目标从“继续治理公开文档边界”切换为“清空 `docs/zh-CN` 中仍然完全缺 frontmatter 的页面，同时把触达页暴露的真实格式错误一并收口”。
|
||||
- 本轮执行的修复：
|
||||
- 为 `best-practices`、`getting-started`、`source-generators`、`tutorials` 等目录下共 `22` 个页面补齐
|
||||
`title` / `description` frontmatter
|
||||
- 修复 `docs/zh-CN/best-practices/multiplayer.md` 末尾缺失的代码块闭合符
|
||||
- 修复 `docs/zh-CN/source-generators/*.md` 与 `docs/zh-CN/troubleshooting.md` 中一组缺少 `.md` 后缀或目录索引写法不兼容当前 validator 的站内链接
|
||||
|
||||
### 当前决策（RP-025）
|
||||
|
||||
- 对文档批处理，优先选择“元数据缺口 + 顺手修复真实结构错误”的组合，而不扩成正文语义刷新或大规模 code fence language 治理。
|
||||
- 当 focused validator 暴露的是触达页上的真实错误（如坏链、未闭合代码块）时，同批次直接收口；仅把纯 warning 留给下一轮专门治理。
|
||||
- 本轮结束时，`docs/zh-CN` 已没有“完全缺 frontmatter”的页面；下一批最稳定的切片是 `docs/zh-CN/index.md` 与
|
||||
`docs/zh-CN/tutorials/basic/01-07.md` 这 `8` 个“已有 frontmatter 但缺 `title` / `description`”的页面。
|
||||
- 当前已提交分支 diff 仍为 `39` 个文件；将本轮工作连同 tracking / trace 提交后，预计累计 branch diff 约为 `63`
|
||||
个文件，仍低于 `$gframework-batch-boot 75` 的停止阈值。
|
||||
|
||||
### 当前验证（RP-025）
|
||||
|
||||
- frontmatter 缺口巡检：
|
||||
- `for f in $(find docs/zh-CN -type f -name '*.md' | sort); do if ! head -n 5 "$f" | grep -q '^---$'; then echo "$f"; fi; done`
|
||||
- 结果：本轮前命中 `22` 个页面，当前已全部补齐。
|
||||
- focused validator：
|
||||
- 逐个校验本轮触达的 `22` 个页面
|
||||
- 结果：通过；只剩 `best-practices/architecture-patterns.md`、`best-practices/index.md`、`contributing.md`、
|
||||
`troubleshooting.md` 与 `tutorials/index.md` 的既有代码块语言 warning。
|
||||
- 站点构建：
|
||||
- `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；仅保留既有大 chunk warning。
|
||||
- 后续候选扫描：
|
||||
- `python3 - <<'PY' ...`（扫描已有 frontmatter 但缺 `title` / `description` 的页面）
|
||||
- 结果：命中 `docs/zh-CN/index.md` 与 `docs/zh-CN/tutorials/basic/01-07.md` 共 `8` 个页面，可作为下一批 metadata 修复入口。
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 继续执行 `$gframework-batch-boot 75` 时，优先补齐 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 的
|
||||
`title` / `description` 缺口。
|
||||
2. 若仍有余量，再按目录收口 `best-practices`、`contributing`、`troubleshooting`、`tutorials/index.md`
|
||||
的代码块语言 warning，而不是跨全站混做。
|
||||
|
||||
### 当前恢复点：RP-024
|
||||
|
||||
- 根据用户反馈，将本轮目标重定义为“清理公开文档中的治理盘点式内容，并把同类约束补进仓库规范与 doc-refresh skill”。
|
||||
- 用户随后补充明确使用 `$gframework-batch-boot 75`，因此继续沿用 `origin/main` 作为固定基线，并把 `75` changed
|
||||
files 作为主停止条件。
|
||||
- 本轮执行的修复：
|
||||
- 在 `AGENTS.md`、`.agents/skills/_shared/DOCUMENTATION_STANDARDS.md` 与
|
||||
`.agents/skills/gframework-doc-refresh/SKILL.md` 中新增公开文档边界规则，禁止把 inventory、覆盖基线、
|
||||
恢复点、review backlog 和治理批次写入 `README.md` 与 `docs/**`
|
||||
- 将 `docs/zh-CN/core/index.md`、`core/cqrs.md`、`game/index.md`、
|
||||
`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`、`ecs/index.md`、
|
||||
`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md` 的 XML 覆盖 / inventory 段落改写成读者导向的源码阅读入口
|
||||
- 继续收口 `api-reference/index.md`、`contributor/development-environment.md` 与
|
||||
`source-generators/*.md` 中的内部术语，例如 `landing page`、`验证基线`、`目标类型基线`
|
||||
- 为 `docs/zh-CN/contributor/development-environment.md` 补齐 frontmatter，使其满足当前文档规范
|
||||
|
||||
### 当前决策（RP-024）
|
||||
|
||||
- 公开文档只承载采用路径、阅读入口、模块边界和可验证示例；治理盘点、覆盖状态和恢复点一律留在 `ai-plan/**`。
|
||||
- 当 XML 治理结果需要体现在公开文档里时，只输出“优先看哪些类型 / 命名空间 / 契约以及为什么”，不输出计数、日期或状态表。
|
||||
- `$gframework-batch-boot 75` 的基线采用 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）。
|
||||
- 由于当前 `HEAD` 仍与 `origin/main` 对齐，分支级 diff 暂时仍为 `0`；提交前工作树待提交范围为 `16` 个文件、
|
||||
`224` changed lines，因此本轮仍远低于 `75` 文件阈值。
|
||||
- 在完成“公开文档边界”收口后，继续沿同一阈值推进一个新的低风险批次：为 `docs/zh-CN/core/*.md` 历史页面补齐 frontmatter。
|
||||
- 当 validator 因本轮触达页面暴露真实坏链时，直接在同批次内修复；当只剩历史 warning（如缺少代码块语言标记）时，本轮停止扩张。
|
||||
|
||||
### 当前验证（RP-024）
|
||||
|
||||
- 同类治理内容巡检：
|
||||
- `rg -n 'XML Inventory|XML 覆盖基线|XML 状态|基线状态|盘点|治理优先级|审计入口|覆盖基线|恢复点|验证基线|目标类型基线|目标字段基线|类型审计|契约审计|源码 / API' docs/zh-CN README.md -g '*.md'`
|
||||
- 结果：公开页已无同类命中；剩余 `inventory` 命中仅来自正常代码示例变量名。
|
||||
- skill 自检：
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`
|
||||
- 结果：均通过；代表模块的 README / docs 入口映射仍有效。
|
||||
- 全量 docs 校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
|
||||
- 结果：失败；暴露 `53` 个仓库既有历史问题（缺少 frontmatter、坏链、未标语言代码块），不属于本轮改动。
|
||||
- focused validator：
|
||||
- 逐个校验本轮触达的 `13` 个公开文档页面
|
||||
- 结果：全部通过。
|
||||
- 站点构建：
|
||||
- `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；仅保留既有大 chunk warning。
|
||||
- `core` frontmatter 波次：
|
||||
- 已补齐 `docs/zh-CN/core/*.md` 中 `21` 个历史页面的 frontmatter。
|
||||
- 过程中修复 `docs/zh-CN/core/ioc.md` 的 `ReaderWriterLockSlim` 坏链，以及
|
||||
`docs/zh-CN/core/state-management.md` 的 4 处缺少 `.md` 后缀的站内链接。
|
||||
- `python3 - <<'PY' ...` 检查结果为 `ALL_HAVE_FRONTMATTER`，说明 `docs/zh-CN/core/` 目录当前已无 frontmatter 缺口。
|
||||
- focused validator 对这 `21` 个页面全部通过；剩余输出仅为既有代码块语言 warning。
|
||||
- `bun run build` 在修复后再次通过。
|
||||
- 当前阈值状态：
|
||||
- `git diff --name-only origin/main...HEAD | wc -l` => `18`
|
||||
- `git diff --name-only | wc -l` => `21`
|
||||
- `git diff --numstat` 汇总 => `126` changed lines
|
||||
- 结论：当前已提交分支 diff 仍为 `18` 个文件，待提交新批次再增加 `21` 个文件；即使提交后也仍低于 `75` 文件阈值。
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 继续执行 `$gframework-batch-boot 75` 时，优先按目录做历史 frontmatter / code fence language / 坏链修复，而不是把不同风格的文档语义刷新混成一批。
|
||||
2. 当前批次在 `core` 目录已经不再是“同样机械”的模式，后续若继续应转向其他目录或专门做代码块语言标记治理。
|
||||
|
||||
## 2026-04-23
|
||||
|
||||
### 当前恢复点：RP-023
|
||||
|
||||
- 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。
|
||||
- 本轮目标定义为“继续沿用上一批的 GitHub 外链策略，收口专题页里的裸路径 README 入口”。
|
||||
- 本轮执行的修复：
|
||||
- 将 `docs/zh-CN/core/cqrs.md` 与 `ecs/arch.md` 的仓库 README 入口改为 GitHub `main` blob 外链
|
||||
- 将 `docs/zh-CN/abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 的回跳 README 入口改为可点击链接
|
||||
- 将 `docs/zh-CN/source-generators/priority-generator.md`、`context-aware-generator.md`、
|
||||
`bind-node-signal-generator.md`、`godot-project-generator.md`、`get-node-generator.md`、
|
||||
`auto-register-exported-collections-generator.md` 的推荐阅读 README 入口改为可点击链接
|
||||
- 同步更新 active tracking / trace，记录第二批导航治理与新的恢复点
|
||||
|
||||
### 当前决策（RP-023）
|
||||
|
||||
- 继续使用 `origin/main` 作为 `$gframework-batch-boot 75` 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。
|
||||
- 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。
|
||||
- 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。
|
||||
- 当 docs 页需要跳转到 `docs/` 外部的 README 时，使用 GitHub `main` 分支 blob 外链，而不是跨出 `docs/` 根目录的相对路径。
|
||||
- 第二批继续沿用同一外链策略，避免在同一 docs surface 中混用“裸路径 / 相对死链 / GitHub 外链”三套入口风格。
|
||||
|
||||
### 当前验证（RP-023）
|
||||
|
||||
- 导航热点巡检：
|
||||
- `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
|
||||
- 结果：命中 landing / API 导航页中的裸路径仓库入口，已按本轮批次收口 7 个页面。
|
||||
- 第二批专题页巡检：
|
||||
- `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
|
||||
- 结果：命中 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、`game/scene.md`、
|
||||
`game/ui.md` 与 6 个 `source-generators/*.md` 专题页，均已修复。
|
||||
- 构建校验：
|
||||
- `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；将仓库 README 跳转改为 GitHub `main` blob 外链后，不再触发 VitePress dead link；仅保留既有大 chunk warning。
|
||||
- 当前阈值状态：
|
||||
- `git diff --name-only origin/main...HEAD | wc -l` => `24`
|
||||
- `git diff --numstat origin/main...HEAD` 汇总 => `264` changed lines
|
||||
- 结论：尚未接近 `75` 文件阈值，但剩余命中主要是正文语义性提及，当前批次在低风险模板化导航治理上可先收口。
|
||||
|
||||
### 归档摘要（RP-022）
|
||||
|
||||
- 为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 `.agents/skills/README.md` 补齐数字速记 stop condition 语义。
|
||||
- 明确 `$gframework-batch-boot 75` / `75 2000` 默认绑定 `origin/main` 累计 diff 口径。
|
||||
- 完成第一批 landing / API 导航页 README 外链治理，并通过 `docs/` 站点构建。
|
||||
|
||||
### 归档指针
|
||||
|
||||
- `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 `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。
|
||||
2. 若继续执行文档治理批处理，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接热点，而不是扩成跨模块大波次。
|
||||
@ -12,9 +12,10 @@
|
||||
|
||||
## 当前恢复点
|
||||
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-025`
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-026`
|
||||
- 当前阶段：`Phase 5 - Governance Maintenance`
|
||||
- 当前焦点：
|
||||
- 收口 PR `#282` 的 latest-head review follow-up，保持 active tracking / trace 只承载当前恢复入口
|
||||
- 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明
|
||||
- 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险 metadata 缺口、坏链与 Markdown 结构问题
|
||||
- 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述
|
||||
@ -24,77 +25,19 @@
|
||||
## 当前状态摘要
|
||||
|
||||
- `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
|
||||
- `2026-04-24` 使用 `$gframework-pr-review` 抓取 PR `#282` 后，确认 latest head commit
|
||||
`982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread；4 条建议均已在本地复核并纳入当前恢复点。
|
||||
- 本轮 PR follow-up 仅收口仍然成立的 review 项：
|
||||
- 将过长的 active tracking / trace 瘦身，并把 `RP-023` 到 `RP-025` 的细节迁入 `archive/`
|
||||
- 将 `docs/zh-CN/core/context.md` 的标题本地化为中文读者友好的写法
|
||||
- 统一 `docs/zh-CN/troubleshooting.md` 中 `/zh-CN/core/architecture` 与 `/zh-CN/faq` 的 `.md` 链接写法
|
||||
- `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/`
|
||||
- `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 中按字面量渲染；两处现已在本地统一改为真实泛型写法。
|
||||
- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对
|
||||
`README.md`、`GFramework.*` 与 `docs/zh-CN/**` 执行同类模式巡检，确认剩余热点仅位于
|
||||
`docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处。
|
||||
- 上述 8 处 inline code 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 已统一改为真实
|
||||
泛型写法，避免在 VitePress 中显示字面量 HTML entity。
|
||||
- `2026-04-23` 根据本轮使用反馈，已为 `.agents/skills/gframework-batch-boot/SKILL.md` 与
|
||||
`.agents/skills/README.md` 补充数字速记阈值语义：
|
||||
- `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止”
|
||||
- `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止”
|
||||
- `75 | 2000` 仅作为可理解的 OR 写法保留，不再作为推荐写法，以避免与 shell pipe 混淆
|
||||
- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对
|
||||
`docs/zh-CN/getting-started/index.md`、`core/index.md`、`game/index.md`、`source-generators/index.md`、
|
||||
`api-reference/index.md`、`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`
|
||||
做导航可达性修复，把仓库 README / 根 README 裸路径统一改为指向 GitHub `main` 分支的可点击链接。
|
||||
- 该批次不改变文档语义，只收口 docs 站点中的入口可达性；适合继续作为小步快跑的低风险治理模式。
|
||||
- `2026-04-23` 在同一基线下继续收口第二批专题页导航热点，已将 `core/cqrs.md`、`ecs/arch.md`、
|
||||
`abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 和 6 个
|
||||
`source-generators/*.md` 专题页里的 README 裸路径统一改为 GitHub `main` blob 外链。
|
||||
- 截至提交 `8a11720`（`2026-04-23T21:01:28+08:00`），当前分支相对 `origin/main`（`aa879d2`）的累计 diff
|
||||
为 `24` 个文件、`264` 行，仍低于 `$gframework-batch-boot 75` 的停止阈值；但剩余命中已主要是正文语义性提及，不再适合作为同类批处理。
|
||||
- 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地
|
||||
文件缺陷。
|
||||
- `2026-04-24` 根据用户反馈完成一轮“公开文档边界”治理，并继续按 `$gframework-batch-boot 75` 向前推进：
|
||||
- 在 `AGENTS.md`、`.agents/skills/_shared/DOCUMENTATION_STANDARDS.md` 与
|
||||
`.agents/skills/gframework-doc-refresh/SKILL.md` 中新增硬约束，明确禁止把 inventory、覆盖基线、恢复点、
|
||||
review backlog、治理批次等 contributor-only 内容写进 `README.md` 与 `docs/**`
|
||||
- 将 `docs/zh-CN/core/index.md`、`core/cqrs.md`、`game/index.md`、
|
||||
`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`、`ecs/index.md`、
|
||||
`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md` 中的 XML 覆盖表述改写为面向读者的“源码阅读入口”
|
||||
- 顺手收口 `api-reference/index.md`、`contributor/development-environment.md` 与
|
||||
`source-generators/*.md` 中的内部口吻用语，例如 `landing page`、`验证基线`、`目标类型基线`
|
||||
- focused validator 已覆盖本轮触达的 `13` 个公开文档页面并全部通过；站点构建 `cd docs && bun run build`
|
||||
已通过，仅保留既有大 chunk warning
|
||||
- 当前分支 `HEAD` 仍与 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）对齐；在提交本轮工作前，
|
||||
工作树待提交范围为 `16` 个文件、`224` changed lines，距离 `$gframework-batch-boot 75` 的停止阈值仍很远。
|
||||
- `2026-04-24` 继续在同一 stop condition 下执行第二个低风险批次，集中修复 `docs/zh-CN/core/*.md` 的历史 frontmatter 缺口：
|
||||
- 已为 `architecture.md`、`async-initialization.md`、`command.md`、`configuration.md`、`context.md`、
|
||||
`environment.md`、`events.md`、`extensions.md`、`functional.md`、`ioc.md`、`localization.md`、
|
||||
`logging.md`、`model.md`、`pause.md`、`pool.md`、`property.md`、`query.md`、`rule.md`、
|
||||
`state-management.md`、`system.md`、`utility.md` 补齐 frontmatter
|
||||
- 顺手修复 `core/ioc.md` 的 `xref:System.Threading.ReaderWriterLockSlim` 坏链，以及
|
||||
`core/state-management.md` 中 4 处缺少 `.md` 后缀的站内链接
|
||||
- 当前 `docs/zh-CN/core/*.md` 已全部具备 frontmatter；focused validator 对这 `21` 个页面全部通过，`bun run build`
|
||||
再次通过，仅保留既有大 chunk warning
|
||||
- 截至当前未提交工作树，`HEAD` 相对 `origin/main` 的累计 branch diff 仍为 `18` 个文件；新增待提交批次为 `21` 个文件、
|
||||
`126` changed lines，合并后仍显著低于 `$gframework-batch-boot 75` 的停止阈值。
|
||||
- `2026-04-24` 继续在同一 stop condition 下执行第三个低风险批次，集中清理 `docs/zh-CN` 其余“完全缺 frontmatter”的页面：
|
||||
- 已为 `best-practices/*.md` 中缺口页、`contributing.md`、`faq.md`、`game/config-system.md`、
|
||||
`getting-started/*.md`、`godot/coroutine.md`、6 个 `source-generators/*.md`、`troubleshooting.md`、
|
||||
`tutorials/advanced-patterns.md`、`tutorials/basic/index.md` 与 `tutorials/index.md` 补齐 frontmatter
|
||||
- 在同批次内修复 `best-practices/multiplayer.md` 的未闭合代码块、`source-generators/*.md` 中缺少 `.md`
|
||||
后缀的相对链接，以及 `troubleshooting.md` 里 3 处目录索引死链
|
||||
- 当前 `docs/zh-CN` 已不存在“完全缺 frontmatter”的页面；剩余 metadata 热点只剩
|
||||
`docs/zh-CN/index.md` 与 `docs/zh-CN/tutorials/basic/01-07.md` 共 `8` 个“已有 frontmatter 但缺 title /
|
||||
description”的页面
|
||||
- 本批次落地前，当前分支相对 `origin/main` 的累计 branch diff 为 `39` 个文件；连同本轮工作和 tracking / trace
|
||||
更新后，预计提交后累计 diff 约为 `63` 个文件，仍低于 `$gframework-batch-boot 75` 的停止阈值
|
||||
- `2026-04-23` 到 `2026-04-24` 的批次细节、验证日志与旧恢复建议已迁入：
|
||||
`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md`
|
||||
|
||||
## 当前风险
|
||||
|
||||
@ -102,6 +45,7 @@
|
||||
- `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发
|
||||
`MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。
|
||||
- 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。
|
||||
- PR `#282` 的 `Title check` 仍可能提示标题过泛；这是 GitHub PR 元数据问题，不属于本地文件缺陷。
|
||||
|
||||
## 归档指针
|
||||
|
||||
@ -109,63 +53,27 @@
|
||||
`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-023` 到 `RP-025`）：
|
||||
`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md`
|
||||
- 时间线归档（`RP-001` 到 `RP-016`）：
|
||||
`ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md`
|
||||
- 时间线归档（`RP-023` 到 `RP-025`）：
|
||||
`ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md`
|
||||
|
||||
## 最新验证
|
||||
|
||||
- `2026-04-24` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
|
||||
- 结果：失败；暴露出仓库既有的 `53` 个历史文档问题（大量缺少 frontmatter、既有坏链与未标语言代码块），不由本轮改动引入，因此本轮改用 focused validator 证明任务级结果。
|
||||
- `2026-04-24` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
|
||||
- 结果：通过；确认 `Core` 模块的 README、landing、topic 与 fallback docs 入口仍可解析。
|
||||
- `2026-04-24` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`
|
||||
- 结果：通过；确认 `Game` 模块的 README、landing、topic 与 fallback docs 入口仍可解析。
|
||||
- `2026-04-24` focused validator（逐个校验本轮触达页面）
|
||||
- 结果：通过；`docs/zh-CN/abstractions/core-abstractions.md`、
|
||||
`abstractions/ecs-arch-abstractions.md`、`abstractions/game-abstractions.md`、
|
||||
`api-reference/index.md`、`contributor/development-environment.md`、`core/cqrs.md`、`core/index.md`、
|
||||
`ecs/arch.md`、`ecs/index.md`、`game/index.md`、
|
||||
`source-generators/bind-node-signal-generator.md`、
|
||||
`source-generators/cqrs-handler-registry-generator.md`、
|
||||
`source-generators/get-node-generator.md` 的 frontmatter / links / code blocks 全部通过。
|
||||
- `2026-04-24` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json`
|
||||
- 结果：通过；PR `#282` 处于 `OPEN`，latest head commit 有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread，测试汇总为 `2156 passed`，仅剩 `Title check` 的 inconclusive PR 元数据提示。
|
||||
- `2026-04-24` `rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(?<!\\.md)\\)' docs/zh-CN/troubleshooting.md`
|
||||
- 结果：当前无命中；`/zh-CN/core/architecture` 与 `/zh-CN/faq` 已统一补成显式 `.md` 链接。
|
||||
- `2026-04-24` `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；仅保留既有大 chunk warning。
|
||||
- `2026-04-24` `python3 - <<'PY' ...`（检查 `docs/zh-CN/core/*.md` frontmatter）
|
||||
- 结果：通过；`docs/zh-CN/core/` 当前所有 Markdown 页面均已带 frontmatter。
|
||||
- `2026-04-24` focused validator（逐个校验 `docs/zh-CN/core/*.md` 的 `21` 个页面）
|
||||
- 结果：通过；过程中暴露并已修复 `core/ioc.md` 的 `ReaderWriterLockSlim` 坏链与
|
||||
`core/state-management.md` 的 4 处站内坏链；剩余仅为既有代码块语言 warning，不影响任务级通过。
|
||||
- `2026-04-24` `bun run build`（工作目录：`docs/`，第二次）
|
||||
- 结果：通过；frontmatter 与坏链修复后站点仍可正常构建，仅保留既有大 chunk warning。
|
||||
- `2026-04-24` focused validator（逐个校验第三批触达的 `22` 个页面）
|
||||
- 结果：通过；frontmatter、真实坏链与未闭合代码块问题均已修复，剩余仅为 `best-practices/architecture-patterns.md`、
|
||||
`best-practices/index.md`、`contributing.md`、`troubleshooting.md` 与 `tutorials/index.md` 的既有代码块语言 warning。
|
||||
- `2026-04-24` `bun run build`（工作目录：`docs/`，第三次）
|
||||
- 结果：通过；第三批 frontmatter 与链接修复后站点仍可正常构建，仅保留既有大 chunk warning。
|
||||
- `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，定位到
|
||||
`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` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'`
|
||||
- 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。
|
||||
- `2026-04-23` `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md` 与 `sed -n '1,220p' .agents/skills/README.md`
|
||||
- 结果：确认原文仅描述自然语言 stop condition，没有定义数字速记或多阈值 OR 语义；现已补齐。
|
||||
- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
|
||||
- 结果：确认 landing / API 导航页仍有一批裸路径仓库入口；本轮已先修复 `getting-started`、`core`、`game`、
|
||||
`source-generators`、`api-reference` 与两个 abstractions 页面。
|
||||
- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
|
||||
- 结果：定位第二批专题页导航热点，已修复 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、
|
||||
`game/scene.md`、`game/ui.md` 以及 6 个 `source-generators/*.md` 页面。
|
||||
- `2026-04-23` `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；仓库 README 外链改为 GitHub `main` blob 后，不再触发 VitePress dead link；仅保留既有大 chunk warning。
|
||||
- 结果：通过；文档标题本地化、站内链接修正与 `ai-plan` 归档瘦身落地后站点仍可正常构建，仅保留既有大 chunk warning。
|
||||
|
||||
## 下一步
|
||||
|
||||
1. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8`
|
||||
个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。
|
||||
2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖
|
||||
常见分支阈值场景。
|
||||
2. 推送当前 follow-up commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。
|
||||
3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
|
||||
`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
|
||||
4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
|
||||
|
||||
@ -2,162 +2,42 @@
|
||||
|
||||
## 2026-04-24
|
||||
|
||||
### 当前恢复点：RP-025
|
||||
### 当前恢复点：RP-026
|
||||
|
||||
- 继续沿用 `$gframework-batch-boot 75`，基线保持 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）。
|
||||
- 本轮目标从“继续治理公开文档边界”切换为“清空 `docs/zh-CN` 中仍然完全缺 frontmatter 的页面，同时把触达页暴露的真实格式错误一并收口”。
|
||||
- 本轮执行的修复：
|
||||
- 为 `best-practices`、`getting-started`、`source-generators`、`tutorials` 等目录下共 `22` 个页面补齐
|
||||
`title` / `description` frontmatter
|
||||
- 修复 `docs/zh-CN/best-practices/multiplayer.md` 末尾缺失的代码块闭合符
|
||||
- 修复 `docs/zh-CN/source-generators/*.md` 与 `docs/zh-CN/troubleshooting.md` 中一组缺少 `.md` 后缀或目录索引写法不兼容当前 validator 的站内链接
|
||||
- 使用 `$gframework-pr-review` 抓取 PR `#282`，确认 latest head commit
|
||||
`982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread。
|
||||
- 按“只处理 latest-head unresolved threads 中仍成立的问题”的原则，本轮仅收口 4 条本地可复现的 follow-up：
|
||||
- 将 `tracking.md` 与 `trace.md` 的活动入口瘦身，并把 `RP-023` 到 `RP-025` 的细节迁入新 archive 文件
|
||||
- 将 `docs/zh-CN/core/context.md` 的标题与主标题本地化为 `上下文（Context）`
|
||||
- 将 `docs/zh-CN/troubleshooting.md` 中 `/zh-CN/core/architecture` 与 `/zh-CN/faq` 统一补成显式 `.md` 链接
|
||||
|
||||
### 当前决策（RP-025）
|
||||
### 当前决策（RP-026）
|
||||
|
||||
- 对文档批处理，优先选择“元数据缺口 + 顺手修复真实结构错误”的组合，而不扩成正文语义刷新或大规模 code fence language 治理。
|
||||
- 当 focused validator 暴露的是触达页上的真实错误（如坏链、未闭合代码块）时，同批次直接收口；仅把纯 warning 留给下一轮专门治理。
|
||||
- 本轮结束时，`docs/zh-CN` 已没有“完全缺 frontmatter”的页面；下一批最稳定的切片是 `docs/zh-CN/index.md` 与
|
||||
`docs/zh-CN/tutorials/basic/01-07.md` 这 `8` 个“已有 frontmatter 但缺 `title` / `description`”的页面。
|
||||
- 当前已提交分支 diff 仍为 `39` 个文件；将本轮工作连同 tracking / trace 提交后，预计累计 branch diff 约为 `63`
|
||||
个文件，仍低于 `$gframework-batch-boot 75` 的停止阈值。
|
||||
- PR review follow-up 继续遵守“先本地验证，再决定是否修复”；对已经过时或无法在当前分支复现的评论不做追随式修改。
|
||||
- active `ai-plan` 入口只保留当前恢复点、活动事实、风险、最新验证与下一步；批次细节统一迁入 `archive/`。
|
||||
- `docs/zh-CN` 页面应优先使用中文标题；同一帮助块中的绝对站内链接应保持一致的显式 `.md` 写法。
|
||||
|
||||
### 当前验证（RP-025）
|
||||
### 当前验证（RP-026）
|
||||
|
||||
- frontmatter 缺口巡检：
|
||||
- `for f in $(find docs/zh-CN -type f -name '*.md' | sort); do if ! head -n 5 "$f" | grep -q '^---$'; then echo "$f"; fi; done`
|
||||
- 结果：本轮前命中 `22` 个页面，当前已全部补齐。
|
||||
- focused validator：
|
||||
- 逐个校验本轮触达的 `22` 个页面
|
||||
- 结果：通过；只剩 `best-practices/architecture-patterns.md`、`best-practices/index.md`、`contributing.md`、
|
||||
`troubleshooting.md` 与 `tutorials/index.md` 的既有代码块语言 warning。
|
||||
- PR review 抓取：
|
||||
- `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json`
|
||||
- 结果：通过；PR `#282` 处于 `OPEN`，最新 review 线程与测试状态已成功解析，测试汇总为 `2156 passed`。
|
||||
- 链接巡检：
|
||||
- `rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(?<!\\.md)\\)' docs/zh-CN/troubleshooting.md`
|
||||
- 结果：当前无命中；`/zh-CN/core/architecture` 与 `/zh-CN/faq` 已统一补成显式 `.md` 链接。
|
||||
- 站点构建：
|
||||
- `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；仅保留既有大 chunk warning。
|
||||
- 后续候选扫描：
|
||||
- `python3 - <<'PY' ...`（扫描已有 frontmatter 但缺 `title` / `description` 的页面）
|
||||
- 结果：命中 `docs/zh-CN/index.md` 与 `docs/zh-CN/tutorials/basic/01-07.md` 共 `8` 个页面，可作为下一批 metadata 修复入口。
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 继续执行 `$gframework-batch-boot 75` 时，优先补齐 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 的
|
||||
`title` / `description` 缺口。
|
||||
2. 若仍有余量，再按目录收口 `best-practices`、`contributing`、`troubleshooting`、`tutorials/index.md`
|
||||
的代码块语言 warning，而不是跨全站混做。
|
||||
|
||||
### 当前恢复点：RP-024
|
||||
|
||||
- 根据用户反馈，将本轮目标重定义为“清理公开文档中的治理盘点式内容，并把同类约束补进仓库规范与 doc-refresh skill”。
|
||||
- 用户随后补充明确使用 `$gframework-batch-boot 75`，因此继续沿用 `origin/main` 作为固定基线，并把 `75` changed
|
||||
files 作为主停止条件。
|
||||
- 本轮执行的修复：
|
||||
- 在 `AGENTS.md`、`.agents/skills/_shared/DOCUMENTATION_STANDARDS.md` 与
|
||||
`.agents/skills/gframework-doc-refresh/SKILL.md` 中新增公开文档边界规则，禁止把 inventory、覆盖基线、
|
||||
恢复点、review backlog 和治理批次写入 `README.md` 与 `docs/**`
|
||||
- 将 `docs/zh-CN/core/index.md`、`core/cqrs.md`、`game/index.md`、
|
||||
`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`、`ecs/index.md`、
|
||||
`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md` 的 XML 覆盖 / inventory 段落改写成读者导向的源码阅读入口
|
||||
- 继续收口 `api-reference/index.md`、`contributor/development-environment.md` 与
|
||||
`source-generators/*.md` 中的内部术语，例如 `landing page`、`验证基线`、`目标类型基线`
|
||||
- 为 `docs/zh-CN/contributor/development-environment.md` 补齐 frontmatter，使其满足当前文档规范
|
||||
|
||||
### 当前决策（RP-024）
|
||||
|
||||
- 公开文档只承载采用路径、阅读入口、模块边界和可验证示例；治理盘点、覆盖状态和恢复点一律留在 `ai-plan/**`。
|
||||
- 当 XML 治理结果需要体现在公开文档里时，只输出“优先看哪些类型 / 命名空间 / 契约以及为什么”，不输出计数、日期或状态表。
|
||||
- `$gframework-batch-boot 75` 的基线采用 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）。
|
||||
- 由于当前 `HEAD` 仍与 `origin/main` 对齐，分支级 diff 暂时仍为 `0`；提交前工作树待提交范围为 `16` 个文件、
|
||||
`224` changed lines，因此本轮仍远低于 `75` 文件阈值。
|
||||
- 在完成“公开文档边界”收口后，继续沿同一阈值推进一个新的低风险批次：为 `docs/zh-CN/core/*.md` 历史页面补齐 frontmatter。
|
||||
- 当 validator 因本轮触达页面暴露真实坏链时，直接在同批次内修复；当只剩历史 warning（如缺少代码块语言标记）时，本轮停止扩张。
|
||||
|
||||
### 当前验证（RP-024）
|
||||
|
||||
- 同类治理内容巡检：
|
||||
- `rg -n 'XML Inventory|XML 覆盖基线|XML 状态|基线状态|盘点|治理优先级|审计入口|覆盖基线|恢复点|验证基线|目标类型基线|目标字段基线|类型审计|契约审计|源码 / API' docs/zh-CN README.md -g '*.md'`
|
||||
- 结果：公开页已无同类命中；剩余 `inventory` 命中仅来自正常代码示例变量名。
|
||||
- skill 自检：
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`
|
||||
- 结果：均通过；代表模块的 README / docs 入口映射仍有效。
|
||||
- 全量 docs 校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
|
||||
- 结果：失败；暴露 `53` 个仓库既有历史问题（缺少 frontmatter、坏链、未标语言代码块），不属于本轮改动。
|
||||
- focused validator：
|
||||
- 逐个校验本轮触达的 `13` 个公开文档页面
|
||||
- 结果：全部通过。
|
||||
- 站点构建：
|
||||
- `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；仅保留既有大 chunk warning。
|
||||
- `core` frontmatter 波次：
|
||||
- 已补齐 `docs/zh-CN/core/*.md` 中 `21` 个历史页面的 frontmatter。
|
||||
- 过程中修复 `docs/zh-CN/core/ioc.md` 的 `ReaderWriterLockSlim` 坏链，以及
|
||||
`docs/zh-CN/core/state-management.md` 的 4 处缺少 `.md` 后缀的站内链接。
|
||||
- `python3 - <<'PY' ...` 检查结果为 `ALL_HAVE_FRONTMATTER`，说明 `docs/zh-CN/core/` 目录当前已无 frontmatter 缺口。
|
||||
- focused validator 对这 `21` 个页面全部通过；剩余输出仅为既有代码块语言 warning。
|
||||
- `bun run build` 在修复后再次通过。
|
||||
- 当前阈值状态：
|
||||
- `git diff --name-only origin/main...HEAD | wc -l` => `18`
|
||||
- `git diff --name-only | wc -l` => `21`
|
||||
- `git diff --numstat` 汇总 => `126` changed lines
|
||||
- 结论：当前已提交分支 diff 仍为 `18` 个文件，待提交新批次再增加 `21` 个文件；即使提交后也仍低于 `75` 文件阈值。
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 继续执行 `$gframework-batch-boot 75` 时，优先按目录做历史 frontmatter / code fence language / 坏链修复，而不是把不同风格的文档语义刷新混成一批。
|
||||
2. 当前批次在 `core` 目录已经不再是“同样机械”的模式，后续若继续应转向其他目录或专门做代码块语言标记治理。
|
||||
|
||||
## 2026-04-23
|
||||
|
||||
### 当前恢复点：RP-023
|
||||
|
||||
- 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。
|
||||
- 本轮目标定义为“继续沿用上一批的 GitHub 外链策略，收口专题页里的裸路径 README 入口”。
|
||||
- 本轮执行的修复：
|
||||
- 将 `docs/zh-CN/core/cqrs.md` 与 `ecs/arch.md` 的仓库 README 入口改为 GitHub `main` blob 外链
|
||||
- 将 `docs/zh-CN/abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 的回跳 README 入口改为可点击链接
|
||||
- 将 `docs/zh-CN/source-generators/priority-generator.md`、`context-aware-generator.md`、
|
||||
`bind-node-signal-generator.md`、`godot-project-generator.md`、`get-node-generator.md`、
|
||||
`auto-register-exported-collections-generator.md` 的推荐阅读 README 入口改为可点击链接
|
||||
- 同步更新 active tracking / trace，记录第二批导航治理与新的恢复点
|
||||
|
||||
### 当前决策（RP-023）
|
||||
|
||||
- 继续使用 `origin/main` 作为 `$gframework-batch-boot 75` 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。
|
||||
- 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。
|
||||
- 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。
|
||||
- 当 docs 页需要跳转到 `docs/` 外部的 README 时，使用 GitHub `main` 分支 blob 外链，而不是跨出 `docs/` 根目录的相对路径。
|
||||
- 第二批继续沿用同一外链策略，避免在同一 docs surface 中混用“裸路径 / 相对死链 / GitHub 外链”三套入口风格。
|
||||
|
||||
### 当前验证（RP-023）
|
||||
|
||||
- 导航热点巡检：
|
||||
- `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
|
||||
- 结果：命中 landing / API 导航页中的裸路径仓库入口，已按本轮批次收口 7 个页面。
|
||||
- 第二批专题页巡检：
|
||||
- `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
|
||||
- 结果：命中 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、`game/scene.md`、
|
||||
`game/ui.md` 与 6 个 `source-generators/*.md` 专题页，均已修复。
|
||||
- 构建校验：
|
||||
- `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；将仓库 README 跳转改为 GitHub `main` blob 外链后，不再触发 VitePress dead link；仅保留既有大 chunk warning。
|
||||
- 当前阈值状态：
|
||||
- `git diff --name-only origin/main...HEAD | wc -l` => `24`
|
||||
- `git diff --numstat origin/main...HEAD` 汇总 => `264` changed lines
|
||||
- 结论：尚未接近 `75` 文件阈值，但剩余命中主要是正文语义性提及，当前批次在低风险模板化导航治理上可先收口。
|
||||
|
||||
### 归档摘要（RP-022）
|
||||
|
||||
- 为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 `.agents/skills/README.md` 补齐数字速记 stop condition 语义。
|
||||
- 明确 `$gframework-batch-boot 75` / `75 2000` 默认绑定 `origin/main` 累计 diff 口径。
|
||||
- 完成第一批 landing / API 导航页 README 外链治理，并通过 `docs/` 站点构建。
|
||||
- 结果：通过；本轮文档与 `ai-plan` 调整后站点仍可正常构建，仅保留既有大 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/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md`
|
||||
- `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/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md`
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。
|
||||
2. 若继续执行文档治理批处理，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接热点，而不是扩成跨模块大波次。
|
||||
1. 推送当前 follow-up commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。
|
||||
2. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8` 个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
---
|
||||
title: Context
|
||||
title: 上下文（Context）
|
||||
description: 说明 IArchitectureContext 与 ArchitectureContext 的统一上下文入口和当前推荐用法。
|
||||
---
|
||||
|
||||
# Context
|
||||
# 上下文（Context）
|
||||
|
||||
`IArchitectureContext` 是框架的统一上下文入口。
|
||||
|
||||
|
||||
@ -2053,11 +2053,11 @@ public class MyLoader : IResourceLoader
|
||||
如果问题仍未解决：
|
||||
|
||||
1. 查看 [Core 文档](/zh-CN/core/index.md) 了解更多细节
|
||||
2. 查看 [架构组件](/zh-CN/core/architecture) 了解架构设计
|
||||
2. 查看 [架构组件](/zh-CN/core/architecture.md) 了解架构设计
|
||||
3. 查看 [Godot 集成](/zh-CN/godot/index.md) 了解 Godot 特定问题
|
||||
4. 在 [GitHub Issues](https://github.com/GeWuYou/GFramework/issues) 提交问题
|
||||
5. 查看 [教程](/zh-CN/tutorials/index.md) 中的示例代码
|
||||
6. 查看 [常见问题](/zh-CN/faq) 获取快速答案
|
||||
6. 查看 [常见问题](/zh-CN/faq.md) 获取快速答案
|
||||
|
||||
---
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user