From bd5cdb561f15951dde48ea7ca58bffd4ab95d744 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sat, 25 Apr 2026 11:35:25 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs(readme):=20=E4=BC=98=E5=8C=96=E9=93=BE?= =?UTF-8?q?=E6=8E=A5=E6=A0=87=E7=AD=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 5 个模块 README 的 reader-facing 链接标签，去掉裸路径和文件名式文案 - 保持原有链接目标、章节结构与正文语义不变 --- GFramework.Core.SourceGenerators/README.md | 4 ++-- GFramework.Core/README.md | 12 ++++++------ GFramework.Cqrs.SourceGenerators/README.md | 4 ++-- GFramework.Ecs.Arch/README.md | 8 ++++---- GFramework.Game.SourceGenerators/README.md | 4 ++-- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/GFramework.Core.SourceGenerators/README.md b/GFramework.Core.SourceGenerators/README.md index e644afc5..44faf8ae 100644 --- a/GFramework.Core.SourceGenerators/README.md +++ b/GFramework.Core.SourceGenerators/README.md @@ -91,5 +91,5 @@ ## 对应文档 -- 源码生成器总览：[`../docs/zh-CN/source-generators/index.md`](../docs/zh-CN/source-generators/index.md) -- Core 栏目：[`../docs/zh-CN/core/index.md`](../docs/zh-CN/core/index.md) +- 源码生成器总览：[源码生成器文档首页](../docs/zh-CN/source-generators/index.md) +- Core 栏目：[Core 文档首页](../docs/zh-CN/core/index.md) diff --git a/GFramework.Core/README.md b/GFramework.Core/README.md index b62ff0f1..f36d4af9 100644 --- a/GFramework.Core/README.md +++ b/GFramework.Core/README.md @@ -92,7 +92,7 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions 最小示例见： -- [`../docs/zh-CN/getting-started/quick-start.md`](../docs/zh-CN/getting-started/quick-start.md) +- [快速开始示例](../docs/zh-CN/getting-started/quick-start.md) ## 什么时候继续接别的包 @@ -103,8 +103,8 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions ## 对应文档 -- Core 栏目：[`../docs/zh-CN/core/index.md`](../docs/zh-CN/core/index.md) -- Core 抽象层：[`../docs/zh-CN/abstractions/core-abstractions.md`](../docs/zh-CN/abstractions/core-abstractions.md) -- API 参考入口：[`../docs/zh-CN/api-reference/index.md`](../docs/zh-CN/api-reference/index.md) -- CQRS：[`../docs/zh-CN/core/cqrs.md`](../docs/zh-CN/core/cqrs.md) -- 入门指南：[`../docs/zh-CN/getting-started/index.md`](../docs/zh-CN/getting-started/index.md) +- Core 栏目：[Core 文档首页](../docs/zh-CN/core/index.md) +- Core 抽象层：[Core Abstractions 文档](../docs/zh-CN/abstractions/core-abstractions.md) +- API 参考入口：[API 参考首页](../docs/zh-CN/api-reference/index.md) +- CQRS：[CQRS 文档](../docs/zh-CN/core/cqrs.md) +- 入门指南：[入门指南首页](../docs/zh-CN/getting-started/index.md) diff --git a/GFramework.Cqrs.SourceGenerators/README.md b/GFramework.Cqrs.SourceGenerators/README.md index 18b9f4f5..d735a2a8 100644 --- a/GFramework.Cqrs.SourceGenerators/README.md +++ b/GFramework.Cqrs.SourceGenerators/README.md @@ -63,5 +63,5 @@ RegisterCqrsHandlersFromAssembly(typeof(GameArchitecture).Assembly); ## 对应文档 -- CQRS 栏目：[`../docs/zh-CN/core/cqrs.md`](../docs/zh-CN/core/cqrs.md) -- 源码生成器总览：[`../docs/zh-CN/source-generators/index.md`](../docs/zh-CN/source-generators/index.md) +- CQRS 栏目：[CQRS 文档](../docs/zh-CN/core/cqrs.md) +- 源码生成器总览：[源码生成器文档首页](../docs/zh-CN/source-generators/index.md) diff --git a/GFramework.Ecs.Arch/README.md b/GFramework.Ecs.Arch/README.md index 9d78666e..c2820ef9 100644 --- a/GFramework.Ecs.Arch/README.md +++ b/GFramework.Ecs.Arch/README.md @@ -132,7 +132,7 @@ ecsModule.Update(deltaTime); ## 对应文档入口 -- ECS 总览：[`../docs/zh-CN/ecs/index.md`](../docs/zh-CN/ecs/index.md) -- Arch ECS 集成：[`../docs/zh-CN/ecs/arch.md`](../docs/zh-CN/ecs/arch.md) -- 抽象契约页：[`../docs/zh-CN/abstractions/ecs-arch-abstractions.md`](../docs/zh-CN/abstractions/ecs-arch-abstractions.md) -- 统一 API / XML 导航：[`../docs/zh-CN/api-reference/index.md`](../docs/zh-CN/api-reference/index.md) +- ECS 总览：[ECS 文档首页](../docs/zh-CN/ecs/index.md) +- Arch ECS 集成：[Arch ECS 集成说明](../docs/zh-CN/ecs/arch.md) +- 抽象契约页：[ECS Arch Abstractions 文档](../docs/zh-CN/abstractions/ecs-arch-abstractions.md) +- 统一 API / XML 导航：[API 参考首页](../docs/zh-CN/api-reference/index.md) diff --git a/GFramework.Game.SourceGenerators/README.md b/GFramework.Game.SourceGenerators/README.md index c12a3607..b752e5c2 100644 --- a/GFramework.Game.SourceGenerators/README.md +++ b/GFramework.Game.SourceGenerators/README.md @@ -75,5 +75,5 @@ GameProject/ ## 对应文档 -- 配置系统：[`../docs/zh-CN/game/config-system.md`](../docs/zh-CN/game/config-system.md) -- 源码生成器总览：[`../docs/zh-CN/source-generators/index.md`](../docs/zh-CN/source-generators/index.md) +- 配置系统：[配置系统文档](../docs/zh-CN/game/config-system.md) +- 源码生成器总览：[源码生成器文档首页](../docs/zh-CN/source-generators/index.md) From 9dfee7538db6b8b2712ab949e68f1f0a3f8f05de Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sat, 25 Apr 2026 11:46:17 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs(documentation):=20=E8=A1=A5=E9=BD=90?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=BB=A3=E7=A0=81=E5=9D=97=E6=A0=87=E8=AE=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 补齐 Core 热点页与基础教程页的 fenced code block 语言标记 - 更新 documentation-full-coverage-governance 的 tracking 与 trace，记录 RP-034 和 50 文件阈值 --- ...ation-full-coverage-governance-tracking.md | 66 ++++++++++--------- ...entation-full-coverage-governance-trace.md | 54 ++++++++------- docs/zh-CN/core/configuration.md | 2 +- docs/zh-CN/core/extensions.md | 50 +++++++------- docs/zh-CN/core/ioc.md | 44 ++++++------- docs/zh-CN/core/localization.md | 2 +- docs/zh-CN/core/pause.md | 2 +- docs/zh-CN/core/pool.md | 2 +- docs/zh-CN/core/system.md | 14 ++-- docs/zh-CN/tutorials/basic/01-environment.md | 4 +- .../zh-CN/tutorials/basic/02-project-setup.md | 8 +-- .../zh-CN/tutorials/basic/03-counter-basic.md | 4 +- .../tutorials/basic/04-model-refactor.md | 2 +- .../tutorials/basic/05-command-system.md | 4 +- .../tutorials/basic/06-utility-system.md | 14 ++-- docs/zh-CN/tutorials/basic/07-summary.md | 8 +-- 16 files changed, 140 insertions(+), 140 deletions(-) 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 5a443503..a76745e7 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,39 +12,23 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-033` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-034` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理；当前 baseline 已回到 `origin/main`，本批只继续处理新的低风险 reader-facing 缺口 - - 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明，也不再使用反问式或维护者口吻标题 - - 继续优先处理低风险 metadata 缺口、坏链、README 文档入口对齐、reader-friendly 链接标签与 Markdown 结构问题，避免跨模块语义改写 - - 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述 - - 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性 - - 将新的 reader-facing 文档约束同步收口到 `AGENTS.md` 与 `.agents/skills/gframework-doc-refresh/` - - 保持 active tracking / trace 只承载当前恢复入口，把阶段细节留在 `archive/` - - 跟进当前 PR `#287` 的 latest-head review，只收口本地复核后仍成立的文档入口标签一致性问题 + - 按本轮 `$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 ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 -- `2026-04-25` 当前本地 `docs/sdk-update-documentation` 与 `origin/main` 的 committed branch diff 仍为 `0 / 75` 个 changed files；本轮待提交批次已触及 `38` 个文件，落地后仍处于 `$gframework-batch-boot 75` 的安全区间。 -- `2026-04-25` 使用 `$gframework-pr-review` 重新抓取当前 PR `#287` 后，确认 latest head commit - `8209d7a29f35d969fca6258b9817da9b33a203a3` 仅剩 `1` 条 Greptile open thread；本轮继续收口 - `docs/zh-CN/api-reference/index.md` 中站内入口列的链接标签风格不一致问题，并顺手把同页仍直接显示路径的站内入口改为语义化标签。 -- `2026-04-24` 使用 `$gframework-pr-review` 抓取当前 PR `#284` 后，确认 latest head commit - `77540c07f0890cc05b10a849722c87b8bed8f561` 仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread；本轮仅继续收口本地复核后仍成立的 reader-facing 文档入口与 active tracking 精简问题。 -- 本轮 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` 链接写法 -- 本批次将根 `README.md` 中两个仍直接暴露文件路径的内部支撑模块入口改为 reader-friendly 链接标签，避免目录表格继续把路径本身当成入口名称。 -- 本批次继续将 `Core`、`Game`、`Source Generators` 和三篇 `Abstractions` 落地页的纯英文 `title` / H1 改为中文读者友好的入口标题，减少首页与侧边栏扫描成本。 -- 本批次继续将 `core/architecture.md`、`command.md`、`events.md`、`logging.md`、`property.md`、`query.md` 的纯英文 `title` / H1 本地化为中英对照入口标题，保持 Core 子栏目扫描体验一致。 -- 当前批次完成后，纯英文 `title` 扫描只剩 `docs/zh-CN/core/cqrs.md` 的 `CQRS` 与 `docs/zh-CN/index.md` 的 `GFramework`；它们分别属于通用缩写与品牌名，不再作为本轮优先本地化对象。 -- 本批次补齐了 `docs/zh-CN/index.md` 的 `description`，以及 `docs/zh-CN/tutorials/basic/01-07.md` 的 `title` / `description`，让首页和基础教程章节页拥有完整 frontmatter metadata。 -- 本批次统一将教程、最佳实践、Core、Godot 页面里缺显式扩展名的站内 Markdown 链接补齐为 `.md` 或 `index.md`，避免目录链接、绝对路径旧写法与 VitePress 构建解析分叉。 -- 本批次把模块 README、仓库根 README、`docs/index.md` 及多组中文落地页里直接暴露文件路径的入口调整为读者友好的可点击标签，同时补齐语言落地页 metadata 与 README 指向。 -- 本批次进一步清理 `Core`、`Game`、`Ecs`、`Getting Started`、`API Reference`、`Source Generators` 与相关模块 README 中的反问式标题、维护者视角边界说明、产品评审口吻和裸文件名链接标签，并把同类约束补入 `AGENTS.md` 与 `gframework-doc-refresh`。 +- `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` 当前 committed branch diff 为 `5 / 50` 个 changed files；把本轮其余文档文件与 tracking / trace 一并提交后，预计 branch diff 为 `21 / 50`。 +- `2026-04-25` 本轮目录级验证已覆盖 `docs/zh-CN/core` 与 `docs/zh-CN/tutorials/basic`，README 目标文件链接校验和 `docs/` 站点构建也都已通过。 - `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`、 @@ -59,8 +43,8 @@ - `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发 `MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。 - 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。 -- PR `#282` 的 `Title check` 仍可能提示标题过泛；这是 GitHub PR 元数据问题，不属于本地文件缺陷。 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN` 当前会报告若干既有“代码块缺少语言标记”警告；本轮未改这些页面，只记录为现存文档质量尾项。 +- README 链接标签与 `Core` / 教程代码块标记这两类低风险批次已经消化完本轮目标文件，但 `docs/zh-CN` 其他目录仍可能保留未显式标语言的历史代码块。 +- PR `#287` 的 latest-head review 是否还有 open thread 尚未在本轮重新抓取；若继续下一轮，应先复核远端 review 状态再扩批。 ## 归档指针 @@ -77,6 +61,24 @@ ## 最新验证 +- `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` + - 结果：通过；README 链接目标有效。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.SourceGenerators/README.md` + - 结果：通过；README 链接目标有效。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Ecs.Arch/README.md` + - 结果：通过；README 链接目标有效。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game.SourceGenerators/README.md` + - 结果：通过；README 链接目标有效。 +- `2026-04-25` `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` + - 结果：无命中；本轮 5 个 README 已无可见路径式 / 文件名式 Markdown 链接标签残留。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core` + - 结果：通过；`Core` 栏目本轮触达页面的 frontmatter、链接与代码块校验均通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic` + - 结果：通过；基础教程栏目本轮触达页面的 frontmatter、链接与代码块校验均通过。 +- `2026-04-25` `bun run build`（工作目录：`docs/`） + - 结果：通过；README 标签修正与 `Core` / 基础教程代码块语言标记补齐后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-24` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - 结果：通过；PR `#284` 处于 `OPEN`，latest head commit `77540c07f0890cc05b10a849722c87b8bed8f561` 有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread，测试汇总为 `2156 passed`，仅剩 `Title check` 的 inconclusive PR 元数据提示。 - `2026-04-24` `rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(?(this IContextAware contextAware, ICom **使用示例：** -``` +```csharp public class GameController : IController { public void OnStartButtonClicked() @@ -112,13 +112,13 @@ public class GameController : IController #### SendQuery 扩展方法 -``` +```csharp public static TResult SendQuery(this IContextAware contextAware, IQuery query) ``` **使用示例：** -``` +```csharp public class InventoryController : IController { public void ShowInventory() @@ -134,7 +134,7 @@ public class InventoryController : IController #### SendEvent 扩展方法 -``` +```csharp // 发送无参事件 public static void SendEvent(this IContextAware contextAware) where T : new() @@ -144,7 +144,7 @@ public static void SendEvent(this IContextAware contextAware, T e) where T : **使用示例：** -``` +```csharp public class PlayerModel : AbstractModel, IContextAware { public void TakeDamage(int damage) @@ -169,13 +169,13 @@ public class PlayerModel : AbstractModel, IContextAware #### RegisterEvent 扩展方法 -``` +```csharp public static IUnRegister RegisterEvent(this IContextAware contextAware, Action handler) ``` **使用示例：** -``` +```csharp public class GameController : IController { private IUnRegisterList _unregisterList = new UnRegisterList(); @@ -197,13 +197,13 @@ public class GameController : IController #### UnRegisterEvent 扩展方法 -``` +```csharp public static void UnRegisterEvent(this IContextAware contextAware, Action onEvent) ``` ### GetEnvironment 扩展方法 -``` +```csharp public static T? GetEnvironment(this IContextAware contextAware) where T : class public static IEnvironment GetEnvironment(this IContextAware contextAware) ``` @@ -214,7 +214,7 @@ public static IEnvironment GetEnvironment(this IContextAware contextAware) #### IfType 扩展方法 -``` +```csharp // 最简单的类型判断 public static bool IfType(this object obj, Action action) @@ -235,7 +235,7 @@ public static void IfType( **使用示例：** -``` +```csharp object obj = new MyRule(); // 简单类型判断 @@ -259,7 +259,7 @@ obj.IfType( #### IfType`` 扩展方法 -``` +```csharp public static TResult? IfType( this object obj, Func func @@ -268,7 +268,7 @@ public static TResult? IfType( **使用示例：** -``` +```csharp object obj = new MyRule { Name = "TestRule" }; string? name = obj.IfType(r => r.Name); @@ -276,7 +276,7 @@ string? name = obj.IfType(r => r.Name); #### As 和 Do 扩展方法 -``` +```csharp // 安全类型转换 public static T? As(this object obj) where T : class @@ -286,7 +286,7 @@ public static T Do(this T obj, Action action) **使用示例：** -``` +```csharp // 安全类型转换 obj.As() ?.Execute(); @@ -307,7 +307,7 @@ obj.As() #### SwitchType 扩展方法 -``` +```csharp public static void SwitchType( this object obj, params (Type type, Action action)[] handlers @@ -316,7 +316,7 @@ public static void SwitchType( **使用示例：** -``` +```csharp obj.SwitchType( (typeof(IRule), o => HandleRule((IRule)o)), (typeof(ISystem), o => HandleSystem((ISystem)o)), @@ -330,13 +330,13 @@ obj.SwitchType( #### OrEventExtensions -``` +```csharp public static OrEvent Or(this IEvent self, IEvent e) ``` **使用示例：** -``` +```csharp // 组合多个事件：当任意一个触发时执行 var onAnyInput = onKeyPressed.Or(onMouseClicked).Or(onTouchDetected); @@ -357,7 +357,7 @@ var onAnyDamage = onPhysicalDamage #### UnRegisterListExtension -``` +```csharp // 添加到注销列表 public static void AddToUnregisterList(this IUnRegister self, IUnRegisterList unRegisterList) @@ -368,7 +368,7 @@ public static void UnRegisterAll(this IUnRegisterList self) **使用示例：** -``` +```csharp public class ComplexController : IController { private IUnRegisterList _unregisterList = new UnRegisterList(); @@ -401,7 +401,7 @@ public class ComplexController : IController ### Controller 示例 -``` +```csharp public partial class GameplayController : IController { private IUnRegisterList _unregisterList = new UnRegisterList(); @@ -453,7 +453,7 @@ public partial class GameplayController : IController ### Command 示例 -``` +```csharp public class ComplexGameCommand : AbstractCommand { protected override void OnExecute() @@ -478,7 +478,7 @@ public class ComplexGameCommand : AbstractCommand ### System 示例 -``` +```csharp public class AchievementSystem : AbstractSystem { protected override void OnInit() diff --git a/docs/zh-CN/core/ioc.md b/docs/zh-CN/core/ioc.md index d5c2ba57..dd81ed42 100644 --- a/docs/zh-CN/core/ioc.md +++ b/docs/zh-CN/core/ioc.md @@ -274,7 +274,7 @@ var sortedSystems = container.GetAllSorted((a, b) => ## IoC 容器架构 -``` +```text Architecture (架构层) ├── IocContainer (IoC容器) │ ├── Register() // 泛型注册 @@ -341,7 +341,7 @@ public abstract class Architecture : IArchitecture ### 注册组件到容器 -``` +```csharp public class GameArchitecture : Architecture { protected override void Init() @@ -365,7 +365,7 @@ public class GameArchitecture : Architecture ### 从容器获取组件 -``` +```csharp // 通过扩展方法间接使用 IoC 容器 public class PlayerController : IController { @@ -385,7 +385,7 @@ public class PlayerController : IController ### 内部实现 -``` +```csharp public class IocContainer { // 使用字典存储类型到实例集合的映射 @@ -450,7 +450,7 @@ public class IocContainer ### 注册流程 -``` +```text 用户代码 ↓ RegisterSystem(system) @@ -462,7 +462,7 @@ IocContainer.Register(system) ### 获取流程 -``` +```text 用户代码 ↓ this.GetSystem() @@ -480,7 +480,7 @@ IocContainer.Get() ### 基础使用 -``` +```csharp // 1. 创建容器 var container = new IocContainer(); @@ -495,7 +495,7 @@ service.DoSomething(); ### 接口和实现分离 -``` +```csharp // 定义接口 public interface IDataService { @@ -532,7 +532,7 @@ dataService.SaveData("game data"); ### 注册多个实现 -``` +```csharp var container = new IocContainer(); // 注册多个相同接口的不同实现 @@ -552,7 +552,7 @@ var allServices = container.GetAll(); // 返回两个实例的列 检查容器中是否包含指定类型的实例。 -``` +```csharp public bool Contains() where T : class ``` @@ -566,7 +566,7 @@ public bool Contains() where T : class **使用示例：** -``` +```csharp var container = new IocContainer(); // 检查服务是否已注册 @@ -592,7 +592,7 @@ if (!container.Contains()) 判断容器中是否包含某个具体的实例对象。 -``` +```csharp public bool ContainsInstance(object instance) ``` @@ -606,7 +606,7 @@ public bool ContainsInstance(object instance) **使用示例：** -``` +```csharp var container = new IocContainer(); var service = new MyService(); @@ -636,13 +636,13 @@ if (!container.ContainsInstance(anotherService)) 清空容器中的所有实例。 -``` +```csharp public void Clear() ``` **使用示例：** -``` +```csharp var container = new IocContainer(); // 注册多个服务 @@ -711,7 +711,7 @@ Console.WriteLine($"Contains IService2: {container.Contains()}"); // ### 本框架的 IocContainer -``` +```csharp // 简单直接 var container = new IocContainer(); container.Register(new MyService()); @@ -730,7 +730,7 @@ var service = container.Get(); ### 完整的 IoC 框架（如 Autofac、Zenject） -``` +```csharp // 复杂但功能强大 var builder = new ContainerBuilder(); builder.RegisterType().As().SingleInstance(); @@ -753,7 +753,7 @@ var controller = container.Resolve(); ### 1. 在架构初始化时注册 -``` +```csharp public class GameArchitecture : Architecture { protected override void Init() @@ -776,7 +776,7 @@ public class GameArchitecture : Architecture ### 2. 使用接口类型注册 -``` +```csharp // ❌ 不推荐：直接使用实现类 RegisterSystem(new ConcreteSystem()); var system = GetSystem(); @@ -788,7 +788,7 @@ var system = GetSystem(); ### 3. 避免运行时频繁注册 -``` +```csharp // ❌ 不好：游戏运行时频繁注册 void Update() { @@ -804,7 +804,7 @@ protected override void Init() ### 4. 检查 null 返回值 -``` +```csharp // 获取可能不存在的服务 var service = container.Get(); if (service != null) @@ -819,7 +819,7 @@ else ### 5. 合理使用容器冻结 -``` +```csharp // 在架构初始化完成后冻结容器，防止意外修改 protected override void OnInit() { diff --git a/docs/zh-CN/core/localization.md b/docs/zh-CN/core/localization.md index 30193b19..fc636244 100644 --- a/docs/zh-CN/core/localization.md +++ b/docs/zh-CN/core/localization.md @@ -119,7 +119,7 @@ bool ValidateOnLoad { get; set; } // 是否在加载时验证，默认 t ### 目录结构 -``` +```text res://localization/ ├── eng/ # 英文 │ ├── common.json # 通用文本 diff --git a/docs/zh-CN/core/pause.md b/docs/zh-CN/core/pause.md index a4720896..7bd39461 100644 --- a/docs/zh-CN/core/pause.md +++ b/docs/zh-CN/core/pause.md @@ -26,7 +26,7 @@ description: 说明 GFramework.Core 暂停管理系统的栈模型、作用域 暂停系统使用栈结构管理暂停请求。每次调用 `Push` 会将暂停请求压入栈中，调用 `Pop` 会从栈中移除对应的请求。只有当栈为空时，游戏才会恢复运行。 -``` +```text 栈深度 3: [暂停原因: "库存界面"] 栈深度 2: [暂停原因: "对话框"] 栈深度 1: [暂停原因: "暂停菜单"] diff --git a/docs/zh-CN/core/pool.md b/docs/zh-CN/core/pool.md index fd0ab7ff..b0b6a381 100644 --- a/docs/zh-CN/core/pool.md +++ b/docs/zh-CN/core/pool.md @@ -45,7 +45,7 @@ public interface IPoolableObject **生命周期：** -``` +```text 创建 → Acquire（从池取出）→ 使用 → Release（放回池）→ 可再次 Acquire ↓ Pool Destroy → OnPoolDestroy → 销毁 diff --git a/docs/zh-CN/core/system.md b/docs/zh-CN/core/system.md index 8e3e3557..ddbcc963 100644 --- a/docs/zh-CN/core/system.md +++ b/docs/zh-CN/core/system.md @@ -287,7 +287,7 @@ await architecture.InitializeAsync(); ### 1. 事件驱动的 System -``` +```csharp public class InventorySystem : AbstractSystem { protected override void OnInit() @@ -353,7 +353,7 @@ public class InventorySystem : AbstractSystem ### 2. 定时更新的 System -``` +```csharp public class BuffSystem : AbstractSystem { private List _activeBuffs = new(); @@ -405,7 +405,7 @@ public class BuffSystem : AbstractSystem ### 3. 跨 System 协作 -``` +```csharp public class QuestSystem : AbstractSystem { protected override void OnInit() @@ -490,7 +490,7 @@ public class RewardSystem : AbstractSystem ### 4. 管理复杂状态机 -``` +```csharp public class GameStateSystem : AbstractSystem { private GameState _currentState = GameState.MainMenu; @@ -569,7 +569,7 @@ public class GameStateSystem : AbstractSystem - **特点**：主动，响应事件 - **示例**：CombatSystem、QuestSystem -``` +```csharp // ✅ 正确的职责划分 // Model: 存储数据 @@ -617,7 +617,7 @@ public class CombatSystem : AbstractSystem ### 1. 避免频繁的 GetModel/GetSystem -``` +```csharp // ❌ 不好：每次都获取 private void OnUpdate(GameUpdateEvent e) { @@ -642,7 +642,7 @@ private void OnUpdate(GameUpdateEvent e) ### 2. 批量处理 -``` +```csharp public class ParticleSystem : AbstractSystem { private List _particles = new(); diff --git a/docs/zh-CN/tutorials/basic/01-environment.md b/docs/zh-CN/tutorials/basic/01-environment.md index 472675cf..634bc012 100644 --- a/docs/zh-CN/tutorials/basic/01-environment.md +++ b/docs/zh-CN/tutorials/basic/01-environment.md @@ -91,7 +91,7 @@ dotnet --version 你应该看到类似以下输出： -``` +```text 6.0.428 ``` @@ -271,7 +271,7 @@ public partial class TestScript : Node 如果在输出面板看到： -``` +```text ✅ Godot + .NET 环境配置成功！ ✅ .NET 版本: 6.0.x ✅ 准备开始使用 GFramework！ diff --git a/docs/zh-CN/tutorials/basic/02-project-setup.md b/docs/zh-CN/tutorials/basic/02-project-setup.md index cc640e2a..5f5c6ced 100644 --- a/docs/zh-CN/tutorials/basic/02-project-setup.md +++ b/docs/zh-CN/tutorials/basic/02-project-setup.md @@ -40,7 +40,7 @@ next: 在项目根目录创建以下文件夹： -``` +```text MyGFrameworkGame/ ├── scripts/ # C# 脚本代码 │ ├── architecture/ # 架构相关 @@ -368,7 +368,7 @@ public partial class GameEntryPoint : Node 运行游戏（F5），在输出面板应该看到： -``` +```text ✅ GFramework 架构初始化完成！ ``` @@ -378,7 +378,7 @@ public partial class GameEntryPoint : Node 此时，你的项目结构应该如下： -``` +```text MyGFrameworkGame/ ├── scripts/ │ ├── architecture/ @@ -400,7 +400,7 @@ MyGFrameworkGame/ 让我们回顾一下刚才搭建的架构： -``` +```text GameEntryPoint (入口) ↓ GameArchitecture (架构核心) diff --git a/docs/zh-CN/tutorials/basic/03-counter-basic.md b/docs/zh-CN/tutorials/basic/03-counter-basic.md index 78294790..ddf829f8 100644 --- a/docs/zh-CN/tutorials/basic/03-counter-basic.md +++ b/docs/zh-CN/tutorials/basic/03-counter-basic.md @@ -26,7 +26,7 @@ next: 添加以下节点结构： -``` +```text App (Control) ├── CenterContainer (CenterContainer) │ └── VBoxContainer (VBoxContainer) @@ -226,7 +226,7 @@ SubButton.Pressed += () => ### 执行流程 -``` +```text 用户点击按钮 ↓ Pressed 事件触发 diff --git a/docs/zh-CN/tutorials/basic/04-model-refactor.md b/docs/zh-CN/tutorials/basic/04-model-refactor.md index d760874b..0ac5ab97 100644 --- a/docs/zh-CN/tutorials/basic/04-model-refactor.md +++ b/docs/zh-CN/tutorials/basic/04-model-refactor.md @@ -337,7 +337,7 @@ this.RegisterEvent(e => ### 数据流向 -``` +```text 用户点击按钮 ↓ Controller: _counterModel.Increment() diff --git a/docs/zh-CN/tutorials/basic/05-command-system.md b/docs/zh-CN/tutorials/basic/05-command-system.md index 0fae9533..2058e4ba 100644 --- a/docs/zh-CN/tutorials/basic/05-command-system.md +++ b/docs/zh-CN/tutorials/basic/05-command-system.md @@ -83,7 +83,7 @@ AddButton.Pressed += async () => **Command（命令）** 是一种设计模式，它将"请求"封装成对象： -``` +```text 用户操作 → Command → Model ``` @@ -496,7 +496,7 @@ AddButton.Pressed += () => 现在我们的架构已经很清晰了： -``` +```text View → Controller → Command → Model → Event → View ``` diff --git a/docs/zh-CN/tutorials/basic/06-utility-system.md b/docs/zh-CN/tutorials/basic/06-utility-system.md index 9442bdcb..43df22b5 100644 --- a/docs/zh-CN/tutorials/basic/06-utility-system.md +++ b/docs/zh-CN/tutorials/basic/06-utility-system.md @@ -486,7 +486,7 @@ protected override void OnInit() 现在我们的架构已经完整： -``` +```text ┌─────────────┐ │ View │ Godot UI 节点 └──────┬──────┘ @@ -520,7 +520,7 @@ protected override void OnInit() ### 数据流 -``` +```text 用户点击按钮 ↓ Controller: SendCommand(IncreaseCommand) @@ -551,7 +551,7 @@ Model: SendEvent(ChangedCountEvent) → 发送事件 ### 单向数据流 -``` +```text Action → Command → Model → Event → View/System ``` @@ -561,7 +561,7 @@ Action → Command → Model → Event → View/System ### 关注点分离 -``` +```text Controller → "做什么" Command → "怎么做" Model → "状态是什么" @@ -571,7 +571,7 @@ Utility → "规则是什么" ### 依赖倒置 -``` +```text 都依赖接口，不依赖具体实现 ICounterModel ← CounterModel @@ -635,7 +635,7 @@ UpdateAchievement(); ### 项目结构 -``` +```text MyGFrameworkGame/ ├── scripts/ │ ├── architecture/ @@ -666,7 +666,7 @@ MyGFrameworkGame/ ### 架构层次 -``` +```text GameEntryPoint (入口) ↓ GameArchitecture (架构) diff --git a/docs/zh-CN/tutorials/basic/07-summary.md b/docs/zh-CN/tutorials/basic/07-summary.md index 6576a175..ca30a1c0 100644 --- a/docs/zh-CN/tutorials/basic/07-summary.md +++ b/docs/zh-CN/tutorials/basic/07-summary.md @@ -113,7 +113,7 @@ this.RegisterEvent(e => ## 完整架构图 -``` +```text ┌──────────────────────────────────────────────┐ │ View (UI) │ │ Godot Nodes (Label, Button) │ @@ -224,7 +224,7 @@ _view.UpdateView(); 数据总是单向流动： -``` +```text Action → Command → Model → Event → View/System ``` @@ -519,7 +519,7 @@ public void ExecuteCommand_ShouldIncrementModel() **按功能模块划分**： -``` +```text scripts/ ├── counter/ │ ├── model/ @@ -537,7 +537,7 @@ scripts/ **按层级划分**： -``` +```text scripts/ ├── model/ │ ├── CounterModel.cs From c95545db922edbc775f432e0f2683014192f0cf0 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sat, 25 Apr 2026 11:47:52 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs(ai-plan):=20=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E6=B2=BB=E7=90=86=E6=81=A2=E5=A4=8D=E7=82=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 tracking 与 trace 的 branch diff 实际值和后续恢复建议 - 记录本轮 README 与代码块标记批次已经提交完成 --- ...cumentation-full-coverage-governance-tracking.md | 13 ++++++------- .../documentation-full-coverage-governance-trace.md | 6 +++--- 2 files changed, 9 insertions(+), 10 deletions(-) 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 a76745e7..10bb88c3 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 @@ -18,7 +18,7 @@ - 按本轮 `$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，仍处于当前批次阈值安全区间 + - 本轮 `19` 个文档文件连同 active tracking / trace 已落地；当前 branch diff 已确认达到 `21 / 50` 个 changed files，仍处于当前批次阈值安全区间 - 下一轮若继续批处理，优先挑选新的低风险 reader-facing 缺口，并保持单批次预计落地规模不超过剩余 headroom ## 当前状态摘要 @@ -27,7 +27,7 @@ - `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` 当前 committed branch diff 为 `5 / 50` 个 changed files；把本轮其余文档文件与 tracking / trace 一并提交后，预计 branch diff 为 `21 / 50`。 +- `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/` 站点构建也都已通过。 - `Game` persistence docs surface 当前以 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 作为最小巡检集合；若后续 README、runtime public API 或 `PersistenceTests` 变动，应优先复核这一组页面。 @@ -111,10 +111,9 @@ ## 下一步 -1. 提交当前批次后，重新计算 `origin/main...HEAD` 的实际 branch diff，确认本轮落地值是否与预计的 `21 / 50` 一致。 -2. 若继续下一轮 `$gframework-batch-boot 50`，优先重新抓取 `$gframework-pr-review` 确认 PR `#287` 的 latest-head review 是否还有 open thread。 -3. 后续若继续处理 reader-facing 文档问题，优先筛查剩余页面里的维护者视角限制说明、模块 README 中仍可能存在的裸路径标签，以及 `docs/zh-CN` 其他目录里的代码块语言标记缺口。 -4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 +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`、 `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 -5. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、 +4. 若后续分支继续调整 `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 1fa99a90..e36fc8a8 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 @@ -7,7 +7,7 @@ - 本轮按 `$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`。 -- 以当前 write set 估算，本轮文档文件与 active tracking / trace 一并提交后，branch diff 预计为 `21 / 50` 个 changed files，仍有后续小批次空间。 +- 当前批次已提交为 `9dfee75`（`docs(documentation): 补齐文档代码块标记`）；提交后实际 branch diff 为 `21 / 50` 个 changed files，仍有后续小批次空间。 ### 当前决策（RP-034） @@ -43,5 +43,5 @@ ### 下一步 -1. 提交当前批次后，复算 `origin/main...HEAD` 的实际 changed-file 数，确认是否与预计的 `21 / 50` 一致。 -2. 若继续下一轮 `$gframework-batch-boot 50`，优先重新抓取 `$gframework-pr-review`，再选择新的低风险 reader-facing 文档切片。 +1. 若继续下一轮 `$gframework-batch-boot 50`，优先重新抓取 `$gframework-pr-review`，再选择新的低风险 reader-facing 文档切片。 +2. 当前 branch diff 为 `21 / 50`，后续单批次仍应控制在剩余 `29` 个 changed files 的 headroom 内。