mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
docs(documentation): 收口文档批处理治理
- 优化根 README、模块 README 与抽象层页面的 reader-facing 文案和语义化链接标签 - 补充 tutorials、troubleshooting、best-practices、contributing、godot/resource 的代码块语言标记 - 更新 documentation-full-coverage-governance 的恢复点、验证结果与批处理停止条件
This commit is contained in:
gewuyou
parent
094e29ed8b
commit
54b8e5770a
@ -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`
|
||||
|
||||
@ -60,10 +60,10 @@
|
||||
| `Functional/` | `Option`、`Result` 等轻量函数式工具 |
|
||||
| `Extensions/` | 上下文与集合等扩展方法 |
|
||||
|
||||
## XML 覆盖基线
|
||||
## XML 阅读入口
|
||||
|
||||
截至 `2026-04-22`，已按顶层目录对 `GFramework.Core` 的公开 / 内部类型声明做过一轮轻量盘点；当前主目录族的类型声明都已带
|
||||
XML 注释。这里先保留阅读基线，成员级 ``<param>`` / ``<returns>`` / 生命周期语义审计仍属于后续治理项。
|
||||
截至 `2026-04-22`，下面这份目录视图可以帮助你快速定位 `GFramework.Core` 的类型级 XML 文档入口；当前主目录族的类型声明都已带
|
||||
XML 注释。更细的参数、返回值和生命周期语义，适合在阅读对应类型与成员时继续结合源码确认。
|
||||
|
||||
| 类型族 | 基线状态 | 代表类型 |
|
||||
| --- | --- | --- |
|
||||
|
||||
@ -33,9 +33,9 @@
|
||||
| `IArchSystemAdapter.cs` | 让 ECS 系统适配到 GFramework `ISystem` 生命周期的接口 |
|
||||
| `ArchOptions.cs` | `WorldCapacity`、`EnableStatistics`、`Priority` 等配置对象 |
|
||||
|
||||
## XML 阅读基线
|
||||
## XML 阅读入口
|
||||
|
||||
下表记录当前契约包的类型声明级 XML 基线，方便把 README、站内抽象页与源码阅读顺序对齐。
|
||||
下表汇总当前契约包的类型级 XML 文档入口，方便把 README、站内抽象页与源码阅读顺序对齐。
|
||||
|
||||
| 类型族 | 代表类型 | XML 状态 | 阅读重点 |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
@ -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 状态 | 阅读重点 |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
@ -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 注释，用来帮助你建立契约层阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。
|
||||
|
||||
| 契约族 | 基线状态 | 代表类型 | 阅读重点 |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
@ -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 注释，用来帮助你定位生成器入口；具体诊断消息、生成输出和兼容性语义仍建议回到源码与测试继续核对。
|
||||
|
||||
| 类型族 | 基线状态 | 代表类型 | 阅读重点 |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
@ -169,10 +169,10 @@
|
||||
|
||||
这两部分一般被上层子系统消费，不是多数项目的第一接入点。
|
||||
|
||||
## XML 覆盖基线
|
||||
## XML 阅读入口
|
||||
|
||||
下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game` 做的一轮轻量 XML 盘点结果：只统计公开 /
|
||||
内部类型声明是否带 XML 注释，用来建立运行时阅读入口；成员级参数、返回值、异常和生命周期说明仍需要在后续 API 波次继续细化。
|
||||
下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game` 类型级 XML 文档入口：只统计公开 /
|
||||
内部类型声明是否带 XML 注释，用来帮助你确定运行时阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。
|
||||
|
||||
| 子系统 | 基线状态 | 代表类型 | 阅读重点 |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
@ -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) |
|
||||
|
||||
## 文档导航
|
||||
|
||||
@ -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` 与相关专题页是否仍保持一致。
|
||||
|
||||
@ -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` 停止并提交，后续若要继续，应以新的低风险模式或新的热点清单重新建批。
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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)
|
||||
|
||||
## 使用建议
|
||||
|
||||
|
||||
@ -3043,7 +3043,7 @@ public class AchievementSystem : AbstractSystem
|
||||
|
||||
### 模式选择决策树
|
||||
|
||||
```
|
||||
```text
|
||||
需要管理游戏状态？
|
||||
├─ 是 → 使用状态模式
|
||||
└─ 否 → 继续
|
||||
|
||||
@ -121,7 +121,7 @@ public class GetPlayerPositionQuery : AbstractQuery<Vector2>
|
||||
|
||||
### 1. 项目结构
|
||||
|
||||
```
|
||||
```text
|
||||
GameProject/
|
||||
├── Models/
|
||||
│ ├── PlayerModel.cs
|
||||
|
||||
@ -318,7 +318,7 @@ public TModel RegisterModel<TModel>(TModel model) where TModel : IModel
|
||||
|
||||
使用 Conventional Commits 规范：
|
||||
|
||||
```
|
||||
```text
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
@ -542,7 +542,7 @@ public partial class MyResource : Resource, IHasKey<string>
|
||||
**解答**：
|
||||
推荐按类型和功能组织：
|
||||
|
||||
```
|
||||
```text
|
||||
res://data/
|
||||
├── items/ # 物品资源
|
||||
│ ├── weapons/
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
|
||||
@ -553,7 +553,7 @@ namespace MyGame
|
||||
|
||||
所有代码文件已在上述步骤中提供。项目结构如下：
|
||||
|
||||
```
|
||||
```text
|
||||
MyGame/
|
||||
├── Data/
|
||||
│ ├── PlayerSaveData.cs # 版本 1 数据结构
|
||||
@ -570,7 +570,7 @@ MyGame/
|
||||
|
||||
运行程序后，你将看到类似以下的输出：
|
||||
|
||||
```
|
||||
```text
|
||||
=== 数据迁移系统测试 ===
|
||||
|
||||
--- 注册迁移器 ---
|
||||
|
||||
@ -775,7 +775,7 @@ class Program
|
||||
|
||||
运行程序后，你将看到类似以下的输出：
|
||||
|
||||
```
|
||||
```text
|
||||
=== 函数式编程实践示例 ===
|
||||
|
||||
--- 测试 Option ---
|
||||
|
||||
@ -71,7 +71,7 @@ description: 从零开始使用 GFramework 构建一个完整的 Godot 游戏项
|
||||
|
||||
### 1.3 创建项目结构
|
||||
|
||||
```
|
||||
```text
|
||||
MyShooterGame/
|
||||
├── Scripts/
|
||||
│ ├── Architecture/
|
||||
|
||||
@ -122,7 +122,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习
|
||||
|
||||
### 路径一：快速上手（推荐新手）
|
||||
|
||||
```
|
||||
```text
|
||||
基础教程（全章节） → Godot 集成教程（选择性阅读） → 开始你的项目
|
||||
```
|
||||
|
||||
@ -133,7 +133,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习
|
||||
|
||||
### 路径二：系统学习（推荐完整掌握）
|
||||
|
||||
```
|
||||
```text
|
||||
基础教程 → Godot 集成教程 → 小项目实践 → 高级模式教程
|
||||
```
|
||||
|
||||
@ -144,7 +144,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习
|
||||
|
||||
### 路径三：架构师之路（推荐团队负责人）
|
||||
|
||||
```
|
||||
```text
|
||||
高级模式教程（预览） → 基础教程 → Godot 集成教程 → 高级模式教程（深入） → 架构设计实践
|
||||
```
|
||||
|
||||
|
||||
@ -29,7 +29,7 @@ description: 学习如何使用 GFramework 组织和管理大型游戏项目
|
||||
|
||||
### 1.1 推荐的目录结构
|
||||
|
||||
```
|
||||
```text
|
||||
MyLargeGame/
|
||||
├── src/
|
||||
│ ├── MyGame.Core/ # 核心层
|
||||
@ -1529,7 +1529,7 @@ namespace MyGame
|
||||
|
||||
运行程序后,你将看到类似以下的输出:
|
||||
|
||||
```
|
||||
```text
|
||||
=== 大型游戏项目示例 ===
|
||||
|
||||
=== 初始化游戏架构 ===
|
||||
|
||||
@ -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) - 便捷的扩展方法
|
||||
|
||||
|
||||
@ -689,7 +689,7 @@ class Program
|
||||
|
||||
所有代码文件已在上述步骤中提供。项目结构如下：
|
||||
|
||||
```
|
||||
```text
|
||||
MyGame/
|
||||
├── Resources/
|
||||
│ ├── Texture.cs
|
||||
@ -709,7 +709,7 @@ MyGame/
|
||||
|
||||
运行程序后，你将看到类似以下的输出：
|
||||
|
||||
```
|
||||
```text
|
||||
=== 资源管理最佳实践测试 ===
|
||||
|
||||
资源管理器初始化完成
|
||||
|
||||
@ -810,7 +810,7 @@ class Program
|
||||
|
||||
所有代码文件已在上述步骤中提供。项目结构如下：
|
||||
|
||||
```
|
||||
```text
|
||||
MyGame/
|
||||
├── Data/
|
||||
│ ├── PlayerData.cs
|
||||
@ -829,7 +829,7 @@ MyGame/
|
||||
|
||||
运行程序后，你将看到类似以下的输出：
|
||||
|
||||
```
|
||||
```text
|
||||
=== 存档系统测试 ===
|
||||
|
||||
游戏架构初始化完成
|
||||
|
||||
@ -627,7 +627,7 @@ class Program
|
||||
|
||||
所有代码文件已在上述步骤中提供。项目结构如下：
|
||||
|
||||
```
|
||||
```text
|
||||
MyGame/
|
||||
├── States/
|
||||
│ ├── MenuState.cs
|
||||
@ -645,7 +645,7 @@ MyGame/
|
||||
|
||||
运行程序后，你将看到类似以下的输出：
|
||||
|
||||
```
|
||||
```text
|
||||
=== 状态机系统测试 ===
|
||||
|
||||
状态机系统初始化完成
|
||||
|
||||
@ -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 个测试文件与指定模式匹配。
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user