mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-12 22:03:30 +08:00

gewuyou 10daba3add docs(documentation): 收口贡献指南代码块警告

- 修复 contributing 文档中的 Mermaid 示例围栏写法，消除剩余代码块语言警告
- 更新 documentation-full-coverage-governance 的 tracking 与 trace，记录 RP-037、基线和验证结果

2026-04-25 16:33:34 +08:00

Documentation Full Coverage Governance Trace

2026-04-25

通过 $gframework-batch-boot 50 重新进入后，先按技能要求读取 AGENTS.md、.ai/environment/tools.ai.yaml、ai-plan/public/README.md、active topic tracking / trace，并确认当前 worktree 仍映射到 documentation-full-coverage-governance。
使用显式 git --git-dir=<repo>/.git/worktrees/GFramework-update-documentation --work-tree=<worktree-root> 绑定确认 baseline 采用 origin/main 79934f7（2026-04-25 16:15:55 +08:00）；branch diff vs baseline 当前为 0 files，工作树仅有本批次改动。
全量运行 bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN 后确认 reader-facing 文档仅剩 docs/zh-CN/contributing.md:631 这一条既有代码块语言警告，适合作为单文件低风险批次收口。
将 docs/zh-CN/contributing.md 的 Mermaid 示例从“真实嵌套 triple-backtick”改写为“外层 fenced block + 内层转义围栏文本”，避免当前 validate-code-blocks.sh 的简单 `^```` 状态机把内层 closing fence 误判成缺语言标记的新 opening fence。

当前批处理目标收敛为“消除 contributing.md 中最后一个剩余代码块语言 warning”，不再继续扩展到别的栏目页。
继续沿用 origin/main 作为 branch-size stop condition 基线，主指标仍是 50 changed files；本批次只新增 1 个工作树文件，远未逼近阈值。
对这类“文档中展示 Markdown 代码块”的示例，优先选择仓库现有校验脚本可稳定识别的转义文本写法，而不是依赖嵌套 fenced block 的解析细节。

文档单文件校验：
- bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md
- 结果：通过；docs/zh-CN/contributing.md 不再报告第 631 行代码块语言警告。
文档全量校验：
- bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN
- 结果：通过；当前 docs/zh-CN 的 frontmatter、链接与代码块校验全部通过。
站点构建：
- bun run build（工作目录：docs/）
- 结果：通过；站点仍可构建，仅保留既有大 chunk warning。

本轮从 $gframework-pr-review 重新进入，目标不再是扩批，而是核对 PR #290 latest-head review 仍未关闭的 reader-facing 文档问题。
使用 python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json 抓取后确认：PR #290 最新 reviewed commit 为 54b8e5770af9ab3c8a86a396ffa4794fe4bb5181，CodeRabbit 与 Greptile 各有 1 条 open thread，失败检查为 0，测试汇总仍为 2156 passed。
本轮把远端 review 与本地工作树逐项比对后，只接受仍然成立的 5 个 reader-facing 问题：source-generators 侧栏 3 个标签与目标标题不一致、api-reference 侧栏重复暴露跨栏目入口、Core / Ecs.Arch / Game README 仍保留 XML 覆盖基线字段。
当前未提交批次限定在 docs/.vitepress/config.mts、3 个模块 README，以及 active tracking / trace；没有继续扩展到其他未被 review 指向的文档文件。

对 PR review 的处理改成“只修当前 latest-head review 仍成立的问题”，不再延续前一轮的批量普查节奏。
api-reference 侧栏不再承载跨栏目目录跳转；跨模块导航继续保留在 docs/zh-CN/api-reference/index.md 的正文里，避免侧栏在跳出栏目后发生上下文切换。
source-generators 侧栏项统一与目标文档的 H1 / frontmatter title 对齐，避免同一页面在导航、标题与搜索索引里出现多套命名。
模块 README 的 XML 阅读表只保留读者有用的“代表类型 / 阅读重点”，把覆盖计数、日期和 已覆盖 之类治理痕迹全部留在 ai-plan/**。

PR review 抓取：
- python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json
- 结果：通过；PR #290 处于 OPEN，latest head review 还有 2 条 open thread，测试汇总为 2156 passed。
README / 链接校验：
- bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md
- 结果：通过；本轮 3 个 README 调整后链接目标仍然有效。
站点构建：
- bun run build（工作目录：docs/）
- 结果：通过；docs/.vitepress/config.mts 的侧栏调整后站点仍可构建，仅保留既有大 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