diff --git a/GFramework.Core.Abstractions/README.md b/GFramework.Core.Abstractions/README.md index 58c67061..34382544 100644 --- a/GFramework.Core.Abstractions/README.md +++ b/GFramework.Core.Abstractions/README.md @@ -34,10 +34,10 @@ | `Data/` `Serializer/` `Storage/` `Versioning/` | 数据装载、序列化、存储与版本化契约 | | `Enums/` `Properties/` | 架构阶段枚举,以及架构 / logger 相关属性键 | -## XML 覆盖基线 +## XML 阅读入口 -截至 `2026-04-22`,已按顶层目录对 `GFramework.Core.Abstractions` 的公开 / 内部类型声明做过一轮轻量盘点;当前契约目录族的类型声明都已带 -XML 注释。这里记录的是类型族级基线,成员级契约细节仍需要在后续波次继续审计。 +截至 `2026-04-22`,下面这份目录视图可以帮助你快速定位 `GFramework.Core.Abstractions` 的类型级 XML 文档入口;当前契约目录族的类型声明都已带 +XML 注释。更细的契约约束与交互语义,适合在阅读具体接口和成员时继续结合源码确认。 | 类型族 | 基线状态 | 代表类型 | | --- | --- | --- | @@ -57,9 +57,9 @@ XML 注释。这里记录的是类型族级基线,成员级契约细节仍需 - 若你只需要对接口编程,可以仅引用本包,再在应用层自行提供实现 - 若你在写上层模块,优先把公共契约放在 `*.Abstractions`,实现放在对应 runtime 包 -## 重点 XML 关注点 +## 推荐优先阅读的 XML 类型族 -如果你在做契约审计、模块拆分或测试替身,优先看这些类型族的 XML 文档: +如果你在做模块拆分、测试替身或接口适配,优先看这些类型族的 XML 文档: - 架构与模块入口:`IArchitecture`、`IArchitectureContext`、`IServiceModule` - 运行时基础设施:`IIocContainer`、`ILogger`、`IResourceManager`、`IConfigurationManager` diff --git a/GFramework.Core/README.md b/GFramework.Core/README.md index f36d4af9..607fabcb 100644 --- a/GFramework.Core/README.md +++ b/GFramework.Core/README.md @@ -60,10 +60,10 @@ | `Functional/` | `Option`、`Result` 等轻量函数式工具 | | `Extensions/` | 上下文与集合等扩展方法 | -## XML 覆盖基线 +## XML 阅读入口 -截至 `2026-04-22`,已按顶层目录对 `GFramework.Core` 的公开 / 内部类型声明做过一轮轻量盘点;当前主目录族的类型声明都已带 -XML 注释。这里先保留阅读基线,成员级 ```` / ```` / 生命周期语义审计仍属于后续治理项。 +截至 `2026-04-22`,下面这份目录视图可以帮助你快速定位 `GFramework.Core` 的类型级 XML 文档入口;当前主目录族的类型声明都已带 +XML 注释。更细的参数、返回值和生命周期语义,适合在阅读对应类型与成员时继续结合源码确认。 | 类型族 | 基线状态 | 代表类型 | | --- | --- | --- | diff --git a/GFramework.Ecs.Arch.Abstractions/README.md b/GFramework.Ecs.Arch.Abstractions/README.md index 3b01d248..a92a1fc2 100644 --- a/GFramework.Ecs.Arch.Abstractions/README.md +++ b/GFramework.Ecs.Arch.Abstractions/README.md @@ -33,9 +33,9 @@ | `IArchSystemAdapter.cs` | 让 ECS 系统适配到 GFramework `ISystem` 生命周期的接口 | | `ArchOptions.cs` | `WorldCapacity`、`EnableStatistics`、`Priority` 等配置对象 | -## XML 阅读基线 +## XML 阅读入口 -下表记录当前契约包的类型声明级 XML 基线,方便把 README、站内抽象页与源码阅读顺序对齐。 +下表汇总当前契约包的类型级 XML 文档入口,方便把 README、站内抽象页与源码阅读顺序对齐。 | 类型族 | 代表类型 | XML 状态 | 阅读重点 | | --- | --- | --- | --- | diff --git a/GFramework.Ecs.Arch/README.md b/GFramework.Ecs.Arch/README.md index c2820ef9..714c2192 100644 --- a/GFramework.Ecs.Arch/README.md +++ b/GFramework.Ecs.Arch/README.md @@ -119,9 +119,9 @@ ecsModule.Update(deltaTime); | `ArchOptions.cs` | 承载 `WorldCapacity`、`EnableStatistics`、`Priority` 这组运行时配置 | | `Components/*.cs`、`Systems/*.cs` | 提供最小组件与系统示例,帮助对照查询写法和更新模式 | -## XML 阅读基线 +## XML 阅读入口 -下表记录当前模块 README 与源码可对照的类型声明级 XML 基线。 +下表汇总当前模块 README 与源码可对照的类型级 XML 文档入口,方便先抓住 Arch ECS 集成的关键类型。 | 类型族 | 代表类型 | XML 状态 | 阅读重点 | | --- | --- | --- | --- | diff --git a/GFramework.Game.Abstractions/README.md b/GFramework.Game.Abstractions/README.md index 9439de79..4f02b893 100644 --- a/GFramework.Game.Abstractions/README.md +++ b/GFramework.Game.Abstractions/README.md @@ -131,10 +131,10 @@ Scene 与 UI 路由共享这套基础约定。 - `Enums/` - UI/Scene 转场、UI 层级、输入动作、存储类型等公共枚举 -## XML 覆盖基线 +## XML 阅读入口 -下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.Abstractions` 做的一轮轻量 XML 盘点结果:只统计公开 / -内部类型声明是否带 XML 注释,用来建立契约层阅读入口;成员级参数、返回值、异常和生命周期说明仍需要在后续 API 波次继续细化。 +下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game.Abstractions` 类型级 XML 文档入口:只统计公开 / +内部类型声明是否带 XML 注释,用来帮助你建立契约层阅读顺序;更细的参数、返回值、异常和生命周期说明,建议继续回到具体类型与成员确认。 | 契约族 | 基线状态 | 代表类型 | 阅读重点 | | --- | --- | --- | --- | diff --git a/GFramework.Game.SourceGenerators/README.md b/GFramework.Game.SourceGenerators/README.md index b752e5c2..8723ad39 100644 --- a/GFramework.Game.SourceGenerators/README.md +++ b/GFramework.Game.SourceGenerators/README.md @@ -44,9 +44,9 @@ GameProject/ 默认情况下,打包产物会通过 `targets` 把 `schemas/**/*.schema.json` 纳入 `AdditionalFiles`。 -## XML 覆盖基线 +## XML 阅读入口 -下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.SourceGenerators` 做的一轮轻量 XML 盘点结果:只统计公开类型声明是否带 XML 注释,用来建立生成器入口;具体诊断消息、生成输出和兼容性语义仍需要回到源码与测试继续核对。 +下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game.SourceGenerators` 类型级 XML 文档入口:只统计公开类型声明是否带 XML 注释,用来帮助你定位生成器入口;具体诊断消息、生成输出和兼容性语义仍建议回到源码与测试继续核对。 | 类型族 | 基线状态 | 代表类型 | 阅读重点 | | --- | --- | --- | --- | diff --git a/GFramework.Game/README.md b/GFramework.Game/README.md index 586b0b81..597f6760 100644 --- a/GFramework.Game/README.md +++ b/GFramework.Game/README.md @@ -169,10 +169,10 @@ 这两部分一般被上层子系统消费,不是多数项目的第一接入点。 -## XML 覆盖基线 +## XML 阅读入口 -下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game` 做的一轮轻量 XML 盘点结果:只统计公开 / -内部类型声明是否带 XML 注释,用来建立运行时阅读入口;成员级参数、返回值、异常和生命周期说明仍需要在后续 API 波次继续细化。 +下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game` 类型级 XML 文档入口:只统计公开 / +内部类型声明是否带 XML 注释,用来帮助你确定运行时阅读顺序;更细的参数、返回值、异常和生命周期说明,建议继续回到具体类型与成员确认。 | 子系统 | 基线状态 | 代表类型 | 阅读重点 | | --- | --- | --- | --- | diff --git a/README.md b/README.md index 294a91b0..5fc94729 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,8 @@ | 目录 | 定位 | 跟随入口 | | --- | --- | --- | -| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [Core.SourceGenerators 模块 README](GFramework.Core.SourceGenerators/README.md) | -| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [Godot.SourceGenerators 模块 README](GFramework.Godot.SourceGenerators/README.md) | +| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [Core.SourceGenerators 模块说明](GFramework.Core.SourceGenerators/README.md) | +| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [Godot.SourceGenerators 模块说明](GFramework.Godot.SourceGenerators/README.md) | | `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [源码生成器总览](docs/zh-CN/source-generators/index.md) | ## 文档导航 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 10bb88c3..8ba1e64e 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,23 +12,25 @@ ## 当前恢复点 -- 恢复点编号:`DOCUMENTATION-FULL-COVERAGE-GOV-RP-034` +- 恢复点编号:`DOCUMENTATION-FULL-COVERAGE-GOV-RP-035` - 当前阶段:`Phase 5 - Governance Maintenance` - 当前焦点: - - 按本轮 `$gframework-batch-boot 50` 约束继续使用 `origin/main`(`984fb21`,`2026-04-25 11:11:56 +08:00`)作为唯一 baseline,只推进低风险、可切片的文档治理批次 - - 本轮已收口三类目标:5 个模块 README 的语义化链接标签、7 个 `Core` 热点页的代码块语言标记、7 个基础教程页的代码块语言标记 - - 当前已接收 worker A 的 README 切片结果;其余代码块标记批次由主线程统一复核并补齐 - - 本轮 `19` 个文档文件连同 active tracking / trace 已落地;当前 branch diff 已确认达到 `21 / 50` 个 changed files,仍处于当前批次阈值安全区间 - - 下一轮若继续批处理,优先挑选新的低风险 reader-facing 缺口,并保持单批次预计落地规模不超过剩余 headroom + - 按本轮 `$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): 优化链接标签`);当前批次已接受该切片结果。 -- `2026-04-25` 主线程补齐了 `docs/zh-CN/core/configuration.md`、`extensions.md`、`ioc.md`、`localization.md`、`pause.md`、`pool.md`、`system.md` 的裸 fenced code block opening 语言标记。 -- `2026-04-25` 教程批次当前覆盖 `docs/zh-CN/tutorials/basic/01-environment.md` 到 `07-summary.md`,补齐的内容以目录树、流程图和控制台输出为主,统一显式标注为 `text`。 -- `2026-04-25` 当前实际 branch diff 已更新为 `21 / 50` 个 changed files;其中 `5` 个文件来自已提交的 README 标签切片,`16` 个文件来自本轮代码块标记与 active tracking / trace 更新。 -- `2026-04-25` 本轮目录级验证已覆盖 `docs/zh-CN/core` 与 `docs/zh-CN/tutorials/basic`,README 目标文件链接校验和 `docs/` 站点构建也都已通过。 +- `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`、 @@ -43,8 +45,9 @@ - `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder,并在标准 build 中触发 `MSB4276` / `MSB4018`;这是已知环境阻塞,不属于本轮文档回归。 - 当前 WSL 会话里 `git.exe` 可解析但不能执行,应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。 -- README 链接标签与 `Core` / 教程代码块标记这两类低风险批次已经消化完本轮目标文件,但 `docs/zh-CN` 其他目录仍可能保留未显式标语言的历史代码块。 -- PR `#287` 的 latest-head review 是否还有 open thread 尚未在本轮重新抓取;若继续下一轮,应先复核远端 review 状态再扩批。 +- `docs/zh-CN/contributing.md:631` 仍有 1 条既有代码块语言警告;该位置属于嵌套 fenced 示例结构,不适合继续沿用本轮“只补 opening fence”规则自动改写。 +- 当前可用的低风险、可重复批处理切片已经基本消耗完毕;如果继续推进,剩余问题更可能落在非重复性 prose 调整、复杂示例结构或远端 review 反馈,不宜按本轮同一批处理模板继续盲扫。 +- PR `#287` 的 latest-head review 本轮未重新抓取;若继续下一轮,应先复核远端 review 状态再扩批。 ## 归档指针 @@ -61,6 +64,20 @@ ## 最新验证 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md` + - 结果:通过;根 README 与本轮触达的模块 README 链接目标有效。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials` + - 结果:通过;本轮新增触达的 10 个教程页与其余教程页 frontmatter、链接、代码块校验均通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/best-practices` + - 结果:通过;`index.md` 与 `architecture-patterns.md` 的代码块标记补齐后栏目验证通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` + - 结果:通过;错误输出与完整错误信息块补齐为 `text` 后页面验证通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md` + - 结果:通过,但保留 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 示例警告;不属于本轮自动补标规则可安全收口的范围。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/resource.md` + - 结果:通过;`Godot` 资源页剩余 bare opening fence 已补齐语言标记。 +- `2026-04-25` `bun run build`(工作目录:`docs/`) + - 结果:通过;本轮导航补齐、README reader-facing 改写与教程 / 排障 / 资源页代码块语言标记更新后站点仍可构建,仅保留既有大 chunk warning。 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md` - 结果:通过;README 链接目标有效。 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core.SourceGenerators/README.md` @@ -111,9 +128,10 @@ ## 下一步 -1. 若继续下一轮 `$gframework-batch-boot 50`,优先重新抓取 `$gframework-pr-review` 确认 PR `#287` 的 latest-head review 是否还有 open thread;当前相对阈值仍有 `29` 个 changed files 的 headroom。 -2. 后续若继续处理 reader-facing 文档问题,优先筛查剩余页面里的维护者视角限制说明、模块 README 中仍可能存在的裸路径标签,以及 `docs/zh-CN` 其他目录里的代码块语言标记缺口。 -3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API,优先复核 `docs/zh-CN/game/data.md`、 +1. 当前 `$gframework-batch-boot 50` 建议在本轮停止:待当前工作树与 active tracking / trace 一并提交后,累计 branch diff 将为 `34 / 50`,但同类低风险、可重复切片已基本耗尽。 +2. 若继续下一轮,优先重新抓取 `$gframework-pr-review` 确认 PR `#287` 的 latest-head review 是否还有 open thread,再决定是否进入新的非重复性 reader-facing 文档巡检。 +3. 若后续继续处理公开文档,优先人工评估 `docs/zh-CN/contributing.md:631` 的嵌套 fenced 示例是否值得做结构化改写,而不是继续沿用“只补 opening fence”的自动批处理规则。 +4. 若后续分支继续调整 `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`、 +5. 若后续分支继续调整 `Godot` generator 接法,优先复核 `GFramework.Godot.SourceGenerators/README.md`、 `docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。 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 e36fc8a8..22cf7154 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,36 +2,42 @@ ## 2026-04-25 -### 当前恢复点:RP-034 +### 当前恢复点:RP-035 -- 本轮按 `$gframework-batch-boot 50` 执行,baseline 固定为 `origin/main`(`984fb21`,`2026-04-25 11:11:56 +08:00`);开始时 committed branch diff 为 `5 / 50` 个 changed files。 -- 已接受 worker A 的 README 切片结果:5 个模块 README 的 reader-facing 链接标签修正已落在提交 `bd5cdb5`(`docs(readme): 优化链接标签`)。 -- 主线程补齐了 `docs/zh-CN/core` 下 7 个热点页面与 `docs/zh-CN/tutorials/basic` 下 7 个教程页面的裸 fenced code block opening 语言标记,按内容分别落为 `csharp` 或 `text`。 -- 当前批次已提交为 `9dfee75`(`docs(documentation): 补齐文档代码块标记`);提交后实际 branch diff 为 `21 / 50` 个 changed files,仍有后续小批次空间。 +- 本轮按 `$gframework-batch-boot 50` 执行,baseline 重新对齐到最新 `origin/main`(`4ad880c`,`2026-04-25 14:35:38 +08:00`);重新开始时 committed branch diff 为 `0 / 50` 个 changed files。 +- 已接受 worker 批次 `094e29e`(`docs(docs): 统一中文文档导航与语义化链接文案`),该提交补齐了 `abstractions` / `source-generators` / `api-reference` 的中文导航入口,并修复了 `ecs`、`game`、`godot` 目标页面的路径式可见链接标签。 +- 主线程接收并复核了 `abstractions` 2 页 reader-facing 链接标签修正、`best-practices` 2 页和 `troubleshooting` 1 页的代码块语言标记补齐,以及 `tutorials` 10 页目录树 / 路径 / 输出块统一显式标记为 `text`。 +- 主线程还接收了根 README 与 7 个模块 README 的 reader-facing XML 阅读入口改写,并补齐了 `docs/zh-CN/contributing.md`、`docs/zh-CN/godot/resource.md` 的剩余 bare opening fence。 +- 当前未提交工作树连同 active tracking / trace 一并落地后,累计 branch diff 将达到 `34 / 50` 个 changed files;本轮在未触及阈值的情况下停止,因为同类低风险、可重复批处理切片已基本耗尽。 -### 当前决策(RP-034) +### 当前决策(RP-035) -- README 批次只改 reader-facing 可见标签,不改链接目标;复核结果通过后直接接受 worker A 的独立提交,避免主线程重复改写同一组文件。 -- 代码块语言标记批次以 opening fence 为唯一修正点,不重写示例内容;目录树、流程图、控制台输出统一标 `text`,可执行或 API 示例标 `csharp`。 -- 教程 `01` 到 `07` 当前未发现额外裸 opening fence 之外的高风险文案问题,因此本轮不扩展到结构性重写,保持在低语义风险范围内。 +- 继续沿用“导航 / 链接标签”和“bare opening fence 语言标记”两类低语义风险规则,但拒绝把 closing fence 或复杂嵌套 fenced 结构纳入同一自动批处理模板。 +- 对 worker 产出的代码块标记批次一律做主线程复核;发现 closing fence 被误改后已在本轮立即纠正,并把后续批次提示词收紧到“只改 opening fence”。 +- README 治理批次只改 reader-facing 标题、导语和链接可见标签,不删除现有表格、证据链或源码 / 测试导向的阅读线索。 +- 在 `34 / 50` 之前停止本轮,不是因为 headroom 不足,而是因为自动可识别、风险可控的重复切片已经收敛到仅剩 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 警告;该问题更适合后续人工结构化处理。 -### 当前验证(RP-034) +### 当前验证(RP-035) -- README 链接校验: - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh` 逐个验证 5 个目标 README - - 结果:通过;目标链接有效。 -- README 标签复扫: - - `rg -n '\\[[^\\]]*(README\\.md|\\.md|\\.md/|/zh-CN/[^\\]]*)\\]\\([^)]*\\)' GFramework.Core/README.md GFramework.Core.SourceGenerators/README.md GFramework.Cqrs.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Game.SourceGenerators/README.md` - - 结果:无命中;本轮目标 README 已无可见路径式 / 文件名式标签残留。 -- `Core` 校验: - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core` - - 结果:通过;`Core` 栏目 frontmatter、链接与代码块校验通过。 +- README / 链接校验: + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md` + - 结果:通过;根 README 与本轮触达的模块 README 链接目标有效。 - 教程校验: - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic` - - 结果:通过;基础教程栏目 frontmatter、链接与代码块校验通过。 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials` + - 结果:通过;本轮新增触达的 10 个教程页与其余教程页 frontmatter、链接、代码块校验均通过。 +- 最佳实践校验: + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/best-practices` + - 结果:通过;`index.md` 与 `architecture-patterns.md` 的代码块标记补齐后栏目验证通过。 +- 单页校验: + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` + - 结果:通过;错误输出与完整错误信息块补齐为 `text` 后页面验证通过。 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md` + - 结果:通过,但保留 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 示例警告。 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/resource.md` + - 结果:通过;剩余 bare opening fence 已补齐语言标记。 - 站点构建: - `bun run build`(工作目录:`docs/`) - - 结果:通过;仅保留既有大 chunk warning。 + - 结果:通过;本轮导航补齐、README reader-facing 改写与教程 / 排障 / 资源页代码块语言标记更新后站点仍可构建,仅保留既有大 chunk warning。 ### 归档指针 @@ -43,5 +49,6 @@ ### 下一步 -1. 若继续下一轮 `$gframework-batch-boot 50`,优先重新抓取 `$gframework-pr-review`,再选择新的低风险 reader-facing 文档切片。 -2. 当前 branch diff 为 `21 / 50`,后续单批次仍应控制在剩余 `29` 个 changed files 的 headroom 内。 +1. 若继续下一轮,优先重新抓取 `$gframework-pr-review`,确认 PR `#287` 的 latest-head review 是否还有 open thread,再决定是否进入新的非重复性 reader-facing 文档巡检。 +2. 下一轮若仍要扩批,优先人工评估 `docs/zh-CN/contributing.md:631` 的嵌套 fenced 示例是否值得结构化改写,而不是继续沿用本轮的 opening-fence-only 自动修正规则。 +3. 当前轮次建议在 `34 / 50` 停止并提交,后续若要继续,应以新的低风险模式或新的热点清单重新建批。 diff --git a/docs/zh-CN/abstractions/game-abstractions.md b/docs/zh-CN/abstractions/game-abstractions.md index 00e55e6d..73833327 100644 --- a/docs/zh-CN/abstractions/game-abstractions.md +++ b/docs/zh-CN/abstractions/game-abstractions.md @@ -109,10 +109,10 @@ public sealed class ContinueGameCommandHandler ## 阅读顺序 1. 先读本页,确认你是否真的只需要契约层 -2. 再看 [`../game/index.md`](../game/index.md) 了解默认运行时怎么组织这些契约 +2. 再看 [Game 模块总览](../game/index.md) 了解默认运行时怎么组织这些契约 3. 继续读具体专题页: - - [`../game/config-system.md`](../game/config-system.md) - - [`../game/data.md`](../game/data.md) + - [配置系统](../game/config-system.md) + - [数据系统](../game/data.md) - [设置系统](../game/setting.md) - [场景系统](../game/scene.md) - [UI 系统](../game/ui.md) diff --git a/docs/zh-CN/abstractions/index.md b/docs/zh-CN/abstractions/index.md index 4e1efc0c..b6acd585 100644 --- a/docs/zh-CN/abstractions/index.md +++ b/docs/zh-CN/abstractions/index.md @@ -15,9 +15,9 @@ description: GFramework 各抽象层模块的阅读入口与使用边界。 ## 阅读顺序 -- Core 抽象层:[`core-abstractions.md`](./core-abstractions.md) -- Game 抽象层:[`game-abstractions.md`](./game-abstractions.md) -- Ecs.Arch 抽象层:[`ecs-arch-abstractions.md`](./ecs-arch-abstractions.md) +- Core 抽象层:[Core 抽象层说明](./core-abstractions.md) +- Game 抽象层:[Game 抽象层说明](./game-abstractions.md) +- Ecs.Arch 抽象层:[Ecs.Arch 抽象层说明](./ecs-arch-abstractions.md) ## 使用建议 diff --git a/docs/zh-CN/best-practices/architecture-patterns.md b/docs/zh-CN/best-practices/architecture-patterns.md index 93d2dd7a..1cb7637a 100644 --- a/docs/zh-CN/best-practices/architecture-patterns.md +++ b/docs/zh-CN/best-practices/architecture-patterns.md @@ -3043,7 +3043,7 @@ public class AchievementSystem : AbstractSystem ### 模式选择决策树 -``` +```text 需要管理游戏状态? ├─ 是 → 使用状态模式 └─ 否 → 继续 diff --git a/docs/zh-CN/best-practices/index.md b/docs/zh-CN/best-practices/index.md index ab8d236e..f7838a7c 100644 --- a/docs/zh-CN/best-practices/index.md +++ b/docs/zh-CN/best-practices/index.md @@ -121,7 +121,7 @@ public class GetPlayerPositionQuery : AbstractQuery ### 1. 项目结构 -``` +```text GameProject/ ├── Models/ │ ├── PlayerModel.cs diff --git a/docs/zh-CN/contributing.md b/docs/zh-CN/contributing.md index a9708858..e4f7a4e7 100644 --- a/docs/zh-CN/contributing.md +++ b/docs/zh-CN/contributing.md @@ -318,7 +318,7 @@ public TModel RegisterModel<TModel>(TModel model) where TModel : IModel 使用 Conventional Commits 规范: -``` +```text (): diff --git a/docs/zh-CN/godot/resource.md b/docs/zh-CN/godot/resource.md index 7fb78e74..85d82972 100644 --- a/docs/zh-CN/godot/resource.md +++ b/docs/zh-CN/godot/resource.md @@ -542,7 +542,7 @@ public partial class MyResource : Resource, IHasKey **解答**: 推荐按类型和功能组织: -``` +```text res://data/ ├── items/ # 物品资源 │ ├── weapons/ diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 68d1187f..74c55162 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -22,7 +22,7 @@ description: 提供 GFramework 常见安装、架构、事件与运行时问题 **错误信息**: -``` +```text NU1101: Unable to find package GFramework.Core ``` @@ -56,7 +56,7 @@ dotnet add package GFramework.Core --version 1.0.0 **错误信息**: -``` +```text NU1107: Version conflict detected for Microsoft.Extensions.DependencyInjection ``` @@ -93,7 +93,7 @@ NU1107: Version conflict detected for Microsoft.Extensions.DependencyInjection **错误信息**: -``` +```text error NETSDK1045: The current .NET SDK does not support targeting .NET 8.0 ``` @@ -126,7 +126,7 @@ dotnet --version **错误信息**: -``` +```text InvalidOperationException: Architecture is already initialized ``` @@ -166,7 +166,7 @@ var arch = GameArchitecture.Interface; **错误信息**: -``` +```text InvalidOperationException: No service for type 'IPlayerService' has been registered ``` @@ -208,7 +208,7 @@ protected override void ConfigureServices(IServiceCollection services) **错误信息**: -``` +```text NullReferenceException: Object reference not set to an instance of an object ``` @@ -254,7 +254,7 @@ public class SystemB : AbstractSystem **错误信息**: -``` +```text InvalidOperationException: Architecture not fully initialized ``` @@ -799,7 +799,7 @@ private IEnumerator CoroutineWithCleanup() **错误信息**: -``` +```text FileNotFoundException: Could not find file 'res://assets/player.png' ``` @@ -965,7 +965,7 @@ private async void PreloadResources() **错误信息**: -``` +```text NullReferenceException: Object reference not set to an instance of an object ``` @@ -1011,7 +1011,7 @@ await sceneRouter.NavigateToAsync("Game"); **错误信息**: -``` +```text NullReferenceException: Object reference not set to an instance of an object ``` @@ -1108,7 +1108,7 @@ public partial class GameController : Node **错误信息**: -``` +```text InvalidOperationException: Architecture context not found ``` @@ -1635,7 +1635,7 @@ public void DebugPlayerDamage() **完整错误信息**: -``` +```text NU1101: Unable to find package GFramework.Core. No packages exist with this id in source(s): nuget.org ``` @@ -1667,7 +1667,7 @@ dotnet restore **完整错误信息**: -``` +```text System.Collections.Generic.KeyNotFoundException: 未找到类型为 'PlayerModel' 的组件 ``` @@ -1694,7 +1694,7 @@ public class GameArchitecture : Architecture **完整错误信息**: -``` +```text System.InvalidOperationException: Architecture is already initialized ``` @@ -1769,7 +1769,7 @@ AddChild(anchor); **完整错误信息**: -``` +```text System.InvalidCastException: Unable to cast object of type 'Node' to type 'Player' ``` @@ -1804,7 +1804,7 @@ if (GetNode("Player") is Player player) **完整错误信息**: -``` +```text System.ArgumentException: An item with the same key has already been added. Key: PlayerModel ``` @@ -1920,7 +1920,7 @@ public class SystemA : AbstractSystem **完整错误信息**: -``` +```text System.ObjectDisposedException: Cannot access a disposed object. Object name: 'Architecture' ``` @@ -1960,7 +1960,7 @@ public void UseArchitecture() **完整错误信息**: -``` +```text System.IO.FileNotFoundException: Could not find file 'res://assets/player.png' ``` @@ -1997,7 +1997,7 @@ var texture = ResourceLoader.Load<Texture2D>("res://assets/player.png"); **完整错误信息**: -``` +```text System.NotImplementedException: The method or operation is not implemented ``` diff --git a/docs/zh-CN/tutorials/data-migration.md b/docs/zh-CN/tutorials/data-migration.md index 0c04df53..5ad0e689 100644 --- a/docs/zh-CN/tutorials/data-migration.md +++ b/docs/zh-CN/tutorials/data-migration.md @@ -553,7 +553,7 @@ namespace MyGame 所有代码文件已在上述步骤中提供。项目结构如下: -``` +```text MyGame/ ├── Data/ │ ├── PlayerSaveData.cs # 版本 1 数据结构 @@ -570,7 +570,7 @@ MyGame/ 运行程序后,你将看到类似以下的输出: -``` +```text === 数据迁移系统测试 === --- 注册迁移器 --- diff --git a/docs/zh-CN/tutorials/functional-programming.md b/docs/zh-CN/tutorials/functional-programming.md index 121cbd81..538e2797 100644 --- a/docs/zh-CN/tutorials/functional-programming.md +++ b/docs/zh-CN/tutorials/functional-programming.md @@ -775,7 +775,7 @@ class Program 运行程序后,你将看到类似以下的输出: -``` +```text === 函数式编程实践示例 === --- 测试 Option --- diff --git a/docs/zh-CN/tutorials/godot-complete-project.md b/docs/zh-CN/tutorials/godot-complete-project.md index 3545827c..19a0b2c5 100644 --- a/docs/zh-CN/tutorials/godot-complete-project.md +++ b/docs/zh-CN/tutorials/godot-complete-project.md @@ -71,7 +71,7 @@ description: 从零开始使用 GFramework 构建一个完整的 Godot 游戏项 ### 1.3 创建项目结构 -``` +```text MyShooterGame/ ├── Scripts/ │ ├── Architecture/ diff --git a/docs/zh-CN/tutorials/index.md b/docs/zh-CN/tutorials/index.md index 0646beb7..fa4cc05d 100644 --- a/docs/zh-CN/tutorials/index.md +++ b/docs/zh-CN/tutorials/index.md @@ -122,7 +122,7 @@ description: 汇总 GFramework 的基础与进阶教程入口,帮助按学习 ### 路径一:快速上手(推荐新手) -``` +```text 基础教程(全章节) → Godot 集成教程(选择性阅读) → 开始你的项目 ``` @@ -133,7 +133,7 @@ description: 汇总 GFramework 的基础与进阶教程入口,帮助按学习 ### 路径二:系统学习(推荐完整掌握) -``` +```text 基础教程 → Godot 集成教程 → 小项目实践 → 高级模式教程 ``` @@ -144,7 +144,7 @@ description: 汇总 GFramework 的基础与进阶教程入口,帮助按学习 ### 路径三:架构师之路(推荐团队负责人) -``` +```text 高级模式教程(预览) → 基础教程 → Godot 集成教程 → 高级模式教程(深入) → 架构设计实践 ``` diff --git a/docs/zh-CN/tutorials/large-project-organization.md b/docs/zh-CN/tutorials/large-project-organization.md index d2ff8f7e..c58f5fa2 100644 --- a/docs/zh-CN/tutorials/large-project-organization.md +++ b/docs/zh-CN/tutorials/large-project-organization.md @@ -29,7 +29,7 @@ description: 学习如何使用 GFramework 组织和管理大型游戏项目 ### 1.1 推荐的目录结构 -``` +```text MyLargeGame/ ├── src/ │ ├── MyGame.Core/ # 核心层 @@ -1529,7 +1529,7 @@ namespace MyGame 运行程序后,你将看到类似以下的输出: -``` +```text === 大型游戏项目示例 === === 初始化游戏架构 === diff --git a/docs/zh-CN/tutorials/pause-system.md b/docs/zh-CN/tutorials/pause-system.md index 8022b76e..42fd0c6c 100644 --- a/docs/zh-CN/tutorials/pause-system.md +++ b/docs/zh-CN/tutorials/pause-system.md @@ -822,7 +822,7 @@ namespace MyGame.Controllers ### 项目结构 -``` +```text MyGame/ ├── GameArchitecture.cs ├── Systems/ @@ -911,7 +911,7 @@ class Program 运行程序后,你将看到类似以下的输出: -``` +```text === 暂停系统教程 === 暂停系统和处理器初始化完成 @@ -1130,4 +1130,3 @@ class Program - [Utility 层](/zh-CN/core/utility.md) - Utility 详细说明 - [生命周期管理](/zh-CN/core/lifecycle.md) - 组件生命周期 - [扩展方法](/zh-CN/core/extensions.md) - 便捷的扩展方法 - diff --git a/docs/zh-CN/tutorials/resource-management.md b/docs/zh-CN/tutorials/resource-management.md index 52f59464..30f99674 100644 --- a/docs/zh-CN/tutorials/resource-management.md +++ b/docs/zh-CN/tutorials/resource-management.md @@ -689,7 +689,7 @@ class Program 所有代码文件已在上述步骤中提供。项目结构如下: -``` +```text MyGame/ ├── Resources/ │ ├── Texture.cs @@ -709,7 +709,7 @@ MyGame/ 运行程序后,你将看到类似以下的输出: -``` +```text === 资源管理最佳实践测试 === 资源管理器初始化完成 diff --git a/docs/zh-CN/tutorials/save-system.md b/docs/zh-CN/tutorials/save-system.md index f6782998..604b43a6 100644 --- a/docs/zh-CN/tutorials/save-system.md +++ b/docs/zh-CN/tutorials/save-system.md @@ -810,7 +810,7 @@ class Program 所有代码文件已在上述步骤中提供。项目结构如下: -``` +```text MyGame/ ├── Data/ │ ├── PlayerData.cs @@ -829,7 +829,7 @@ MyGame/ 运行程序后,你将看到类似以下的输出: -``` +```text === 存档系统测试 === 游戏架构初始化完成 @@ -963,4 +963,4 @@ MyGame/ - [数据与存档系统](/zh-CN/game/data.md) - 数据系统详细说明 - [对象池系统](/zh-CN/core/pool.md) - 结合对象池复用资源 - [协程系统](/zh-CN/core/coroutine.md) - 异步加载资源 -- [System 层](/zh-CN/core/system.md) - System 详细说明 \ No newline at end of file +- [System 层](/zh-CN/core/system.md) - System 详细说明 diff --git a/docs/zh-CN/tutorials/state-machine-tutorial.md b/docs/zh-CN/tutorials/state-machine-tutorial.md index 587dd37e..9a62f204 100644 --- a/docs/zh-CN/tutorials/state-machine-tutorial.md +++ b/docs/zh-CN/tutorials/state-machine-tutorial.md @@ -627,7 +627,7 @@ class Program 所有代码文件已在上述步骤中提供。项目结构如下: -``` +```text MyGame/ ├── States/ │ ├── MenuState.cs @@ -645,7 +645,7 @@ MyGame/ 运行程序后,你将看到类似以下的输出: -``` +```text === 状态机系统测试 === 状态机系统初始化完成 diff --git a/docs/zh-CN/tutorials/unit-testing.md b/docs/zh-CN/tutorials/unit-testing.md index 7011d539..90f21cfe 100644 --- a/docs/zh-CN/tutorials/unit-testing.md +++ b/docs/zh-CN/tutorials/unit-testing.md @@ -946,7 +946,7 @@ public class BindablePropertyTests 以下是一个完整的测试项目结构示例: -``` +```text MyGame.Tests/ ├── GlobalUsings.cs ├── MyGame.Tests.csproj @@ -997,7 +997,7 @@ dotnet test --collect:"XPlat Code Coverage" ## 测试输出示例 -``` +```text 正在启动测试执行,请稍候... 总共 1 个测试文件与指定模式匹配。