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

gewuyou 54b8e5770a docs(documentation): 收口文档批处理治理

- 优化根 README、模块 README 与抽象层页面的 reader-facing 文案和语义化链接标签

- 补充 tutorials、troubleshooting、best-practices、contributing、godot/resource 的代码块语言标记

- 更新 documentation-full-coverage-governance 的恢复点、验证结果与批处理停止条件

2026-04-25 15:12:08 +08:00

15 KiB

Raw Blame History

Documentation Full Coverage Governance 跟踪

目标

建立一个长期 active topic，持续治理 GFramework 的 README、docs/zh-CN、站点导航、XML 文档和 API 参考链路，避免阶段性刷新完成后再次回漂。

用源码、测试、*.csproj 和必要的 ai-libs/ 证据校正文档
以模块族为单位闭环 README、landing page、专题页、教程入口和 API 参考链路
明确哪些目录是可直接消费模块，哪些只是内部支撑模块
把 XML 文档缺口纳入治理范围，而不是只刷新 Markdown

当前恢复点

恢复点编号：DOCUMENTATION-FULL-COVERAGE-GOV-RP-035
当前阶段：Phase 5 - Governance Maintenance
当前焦点：
- 按本轮 $gframework-batch-boot 50 约束使用最新 origin/main（4ad880c，2026-04-25 14:35:38 +08:00）作为唯一 baseline，只推进低风险、可切片的 reader-facing 文档治理批次
- 已接受 worker 的导航 / 语义化链接批次，提交为 094e29e（docs(docs): 统一中文文档导航与语义化链接文案）
- 当前未提交批次覆盖 abstractions reader-facing 标签、best-practices / troubleshooting / tutorials 代码块语言标记、7 个模块 / 根 README 的 reader-facing XML 阅读入口改写，以及 contributing / godot/resource 的剩余 bare opening fence
- 当前批次连同 active tracking / trace 一并落地后，累计 branch diff 将达到 34 / 50 个 changed files；虽然仍有 16 个文件 headroom，但同类低风险、可重复批处理切片已经基本耗尽
- 若继续下一轮，不应再按当前模式盲目扩批，而应先复核 PR / review 状态，再决定是否进入新的非重复性文档巡检波次

当前状态摘要

Core、Ecs.Arch、Cqrs、Game、Godot 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
2026-04-25 worker A 已完成并提交 5 个模块 README 的 reader-facing 链接标签修正，提交为 bd5cdb5（docs(readme): 优化链接标签）；该切片仍作为本 topic 的已接受历史批次保留。
2026-04-25 最新 origin/main 已推进到 4ad880c；当前 docs/sdk-update-documentation 相对该 baseline 的已提交 branch diff 为 7 / 50 个文件，来自导航与语义化链接批次 094e29e。
2026-04-25 当前未提交工作树额外覆盖 25 个文件：abstractions 2 页链接标签、best-practices 2 页代码块标记、troubleshooting 1 页错误输出标记、tutorials 10 页目录树 / 路径 / 输出块标记、根 / 模块 README 8 页 reader-facing 改写，以及 contributing / godot/resource 2 页剩余 bare opening fence 处理。
2026-04-25 docs/.vitepress/config.mts 已补齐 abstractions、source-generators、api-reference 的中文 sidebar / nav 入口，且 docs/zh-CN/ecs/arch.md、game/*.md、godot/*.md 的原始路径式可见标签已统一为读者可理解的语义化名称。
2026-04-25 docs/zh-CN/tutorials 本轮已额外补齐 10 个非基础教程页的 bare fenced opening 语言标记；目录树、学习路径和控制台输出统一显式标注为 text，未改写示例内容。
2026-04-25 根 README 与 7 个模块 README 当前已把 XML 覆盖基线 / XML 阅读基线 / inventory / 后续治理项 一类 maintainer-facing 标题与导语改为 reader-facing 的“XML 阅读入口 / 推荐优先阅读的 XML 类型族”等表达，保留了现有表格、链接与证据链。
2026-04-25 本轮主线程复核后确认：docs/zh-CN 中可由统一规则安全处理的 bare opening fence 只剩 docs/zh-CN/contributing.md:631 这一处既有嵌套 fenced 示例警告；它不适合继续按当前“只补 opening fence、不碰 closing fence”的批处理规则自动改写。
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 到 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

当前风险

当前 Core / Core.Abstractions、Ecs.Arch、Cqrs、Game 的 XML 治理证据仍主要来自类型与入口级阅读，不等于成员级契约全审计；这类治理状态只应保留在 ai-plan/**，不应再暴露到公开文档。
GFramework.Cqrs 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发 MSB4276 / MSB4018；这是已知环境阻塞，不属于本轮文档回归。
当前 WSL 会话里 git.exe 可解析但不能执行，应继续使用显式 --git-dir / --work-tree 绑定作为默认 Git 策略。
docs/zh-CN/contributing.md:631 仍有 1 条既有代码块语言警告；该位置属于嵌套 fenced 示例结构，不适合继续沿用本轮“只补 opening fence”规则自动改写。
当前可用的低风险、可重复批处理切片已经基本消耗完毕；如果继续推进，剩余问题更可能落在非重复性 prose 调整、复杂示例结构或远端 review 反馈，不宜按本轮同一批处理模板继续盲扫。
PR #287 的 latest-head review 本轮未重新抓取；若继续下一轮，应先复核远端 review 状态再扩批。

归档指针

详细验证历史（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-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

下一步

当前 $gframework-batch-boot 50 建议在本轮停止：待当前工作树与 active tracking / trace 一并提交后，累计 branch diff 将为 34 / 50，但同类低风险、可重复切片已基本耗尽。
若继续下一轮，优先重新抓取 $gframework-pr-review 确认 PR #287 的 latest-head review 是否还有 open thread，再决定是否进入新的非重复性 reader-facing 文档巡检。
若后续继续处理公开文档，优先人工评估 docs/zh-CN/contributing.md:631 的嵌套 fenced 示例是否值得做结构化改写，而不是继续沿用“只补 opening fence”的自动批处理规则。
若后续分支继续调整 Game persistence runtime、README 或公共 API，优先复核 docs/zh-CN/game/data.md、 storage.md、serialization.md、setting.md 与 landing page 是否仍保持同一套职责边界。
若后续分支继续调整 Godot generator 接法，优先复核 GFramework.Godot.SourceGenerators/README.md、 docs/zh-CN/tutorials/godot-integration.md 与相关专题页是否仍保持一致。

15 KiB Raw Blame History Unescape Escape