From 5b7c555472965bc28dc21ac0a11230c35d4835d1 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Fri, 24 Apr 2026 08:38:51 +0800 Subject: [PATCH] =?UTF-8?q?docs(core):=20=E8=A1=A5=E9=BD=90=20Core=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3=20frontmatter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 补充 docs/zh-CN/core 目录 21 个专题页的 frontmatter 与 description - 修复 core/ioc.md 的 ReaderWriterLockSlim 坏链和 core/state-management.md 的站内链接 - 更新 documentation-full-coverage-governance tracking 与 trace，记录本轮批处理指标、验证结果和停止点 --- ...ation-full-coverage-governance-tracking.md | 20 ++++++++++++++++++- ...entation-full-coverage-governance-trace.md | 18 +++++++++++++++-- docs/zh-CN/core/architecture.md | 5 +++++ docs/zh-CN/core/async-initialization.md | 5 +++++ docs/zh-CN/core/command.md | 5 +++++ docs/zh-CN/core/configuration.md | 5 +++++ docs/zh-CN/core/context.md | 5 +++++ docs/zh-CN/core/environment.md | 7 ++++++- docs/zh-CN/core/events.md | 5 +++++ docs/zh-CN/core/extensions.md | 7 ++++++- docs/zh-CN/core/functional.md | 5 +++++ docs/zh-CN/core/ioc.md | 9 +++++++-- docs/zh-CN/core/localization.md | 5 +++++ docs/zh-CN/core/logging.md | 5 +++++ docs/zh-CN/core/model.md | 7 ++++++- docs/zh-CN/core/pause.md | 5 +++++ docs/zh-CN/core/pool.md | 5 +++++ docs/zh-CN/core/property.md | 5 +++++ docs/zh-CN/core/query.md | 5 +++++ docs/zh-CN/core/rule.md | 7 ++++++- docs/zh-CN/core/state-management.md | 13 ++++++++---- docs/zh-CN/core/system.md | 7 ++++++- docs/zh-CN/core/utility.md | 5 +++++ 23 files changed, 151 insertions(+), 14 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 30f602d7..6f3f7d9a 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 @@ -73,6 +73,17 @@ 已通过，仅保留既有大 chunk warning - 当前分支 `HEAD` 仍与 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）对齐；在提交本轮工作前， 工作树待提交范围为 `16` 个文件、`224` changed lines，距离 `$gframework-batch-boot 75` 的停止阈值仍很远。 +- `2026-04-24` 继续在同一 stop condition 下执行第二个低风险批次，集中修复 `docs/zh-CN/core/*.md` 的历史 frontmatter 缺口： + - 已为 `architecture.md`、`async-initialization.md`、`command.md`、`configuration.md`、`context.md`、 + `environment.md`、`events.md`、`extensions.md`、`functional.md`、`ioc.md`、`localization.md`、 + `logging.md`、`model.md`、`pause.md`、`pool.md`、`property.md`、`query.md`、`rule.md`、 + `state-management.md`、`system.md`、`utility.md` 补齐 frontmatter + - 顺手修复 `core/ioc.md` 的 `xref:System.Threading.ReaderWriterLockSlim` 坏链，以及 + `core/state-management.md` 中 4 处缺少 `.md` 后缀的站内链接 + - 当前 `docs/zh-CN/core/*.md` 已全部具备 frontmatter；focused validator 对这 `21` 个页面全部通过，`bun run build` + 再次通过，仅保留既有大 chunk warning +- 截至当前未提交工作树，`HEAD` 相对 `origin/main` 的累计 branch diff 仍为 `18` 个文件；新增待提交批次为 `21` 个文件、 + `126` changed lines，合并后仍显著低于 `$gframework-batch-boot 75` 的停止阈值。 ## 当前风险 @@ -108,6 +119,13 @@ `source-generators/get-node-generator.md` 的 frontmatter / links / code blocks 全部通过。 - `2026-04-24` `bun run build`（工作目录：`docs/`） - 结果：通过；仅保留既有大 chunk warning。 +- `2026-04-24` `python3 - <<'PY' ...`（检查 `docs/zh-CN/core/*.md` frontmatter） + - 结果：通过；`docs/zh-CN/core/` 当前所有 Markdown 页面均已带 frontmatter。 +- `2026-04-24` focused validator（逐个校验 `docs/zh-CN/core/*.md` 的 `21` 个页面） + - 结果：通过；过程中暴露并已修复 `core/ioc.md` 的 `ReaderWriterLockSlim` 坏链与 + `core/state-management.md` 的 4 处站内坏链；剩余仅为既有代码块语言 warning，不影响任务级通过。 +- `2026-04-24` `bun run build`（工作目录：`docs/`，第二次） + - 结果：通过；frontmatter 与坏链修复后站点仍可正常构建，仅保留既有大 chunk warning。 - `2026-04-23` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json` - 结果：通过；PR `#272` 处于 `OPEN`，latest head commit 存在 1 条 Greptile open thread，定位到 `docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。 @@ -128,7 +146,7 @@ ## 下一步 -1. 若继续执行 `$gframework-batch-boot 75`，优先改做标题锚点、站内链接和少量内部术语残留的逐页复核，而不是回到大范围模板化替换。 +1. 若继续执行 `$gframework-batch-boot 75`，优先改做代码块语言标记、少量残余坏链与其他栏目历史 frontmatter 缺口的分目录批次修复。 2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖 常见分支阈值场景。 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.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 3c9592e4..0ded0f56 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 @@ -25,6 +25,8 @@ - `$gframework-batch-boot 75` 的基线采用 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）。 - 由于当前 `HEAD` 仍与 `origin/main` 对齐，分支级 diff 暂时仍为 `0`；提交前工作树待提交范围为 `16` 个文件、 `224` changed lines，因此本轮仍远低于 `75` 文件阈值。 +- 在完成“公开文档边界”收口后，继续沿同一阈值推进一个新的低风险批次：为 `docs/zh-CN/core/*.md` 历史页面补齐 frontmatter。 +- 当 validator 因本轮触达页面暴露真实坏链时，直接在同批次内修复；当只剩历史 warning（如缺少代码块语言标记）时，本轮停止扩张。 ### 当前验证（RP-024） @@ -44,11 +46,23 @@ - 站点构建： - `bun run build`（工作目录：`docs/`） - 结果：通过；仅保留既有大 chunk warning。 +- `core` frontmatter 波次： + - 已补齐 `docs/zh-CN/core/*.md` 中 `21` 个历史页面的 frontmatter。 + - 过程中修复 `docs/zh-CN/core/ioc.md` 的 `ReaderWriterLockSlim` 坏链，以及 + `docs/zh-CN/core/state-management.md` 的 4 处缺少 `.md` 后缀的站内链接。 + - `python3 - <<'PY' ...` 检查结果为 `ALL_HAVE_FRONTMATTER`，说明 `docs/zh-CN/core/` 目录当前已无 frontmatter 缺口。 + - focused validator 对这 `21` 个页面全部通过；剩余输出仅为既有代码块语言 warning。 + - `bun run build` 在修复后再次通过。 +- 当前阈值状态： + - `git diff --name-only origin/main...HEAD | wc -l` => `18` + - `git diff --name-only | wc -l` => `21` + - `git diff --numstat` 汇总 => `126` changed lines + - 结论：当前已提交分支 diff 仍为 `18` 个文件，待提交新批次再增加 `21` 个文件；即使提交后也仍低于 `75` 文件阈值。 ### 下一步 -1. 继续执行 `$gframework-batch-boot 75` 时，优先排查少量公开页里的内部工程术语残留、标题锚点和站内链接热点。 -2. 若后续需要大范围补 frontmatter / code fence language，应单独开一个新的低风险文档治理批次，而不是混入模块语义刷新。 +1. 继续执行 `$gframework-batch-boot 75` 时，优先按目录做历史 frontmatter / code fence language / 坏链修复，而不是把不同风格的文档语义刷新混成一批。 +2. 当前批次在 `core` 目录已经不再是“同样机械”的模式，后续若继续应转向其他目录或专门做代码块语言标记治理。 ## 2026-04-23 diff --git a/docs/zh-CN/core/architecture.md b/docs/zh-CN/core/architecture.md index 9744a844..0fcfbcce 100644 --- a/docs/zh-CN/core/architecture.md +++ b/docs/zh-CN/core/architecture.md @@ -1,3 +1,8 @@ +--- +title: Architecture +description: 说明 GFramework.Core 的 Architecture 入口、生命周期职责与最常用注册 API。 +--- + # Architecture `Architecture` 是 `GFramework.Core` 的运行时入口。它负责三件事： diff --git a/docs/zh-CN/core/async-initialization.md b/docs/zh-CN/core/async-initialization.md index f5db460f..85133890 100644 --- a/docs/zh-CN/core/async-initialization.md +++ b/docs/zh-CN/core/async-initialization.md @@ -1,3 +1,8 @@ +--- +title: 异步初始化指南 +description: 说明 GFramework.Core 异步初始化接口、生命周期顺序与常见接入方式。 +--- + # 异步初始化指南 ## 概述 diff --git a/docs/zh-CN/core/command.md b/docs/zh-CN/core/command.md index 9372b980..057576cf 100644 --- a/docs/zh-CN/core/command.md +++ b/docs/zh-CN/core/command.md @@ -1,3 +1,8 @@ +--- +title: Command +description: 说明 GFramework.Core.Command 旧命令体系的兼容定位、可用基类与当前使用约束。 +--- + # Command 本页只说明 `GFramework.Core.Command` 里的旧命令体系。 diff --git a/docs/zh-CN/core/configuration.md b/docs/zh-CN/core/configuration.md index 9e74e480..8ade1282 100644 --- a/docs/zh-CN/core/configuration.md +++ b/docs/zh-CN/core/configuration.md @@ -1,3 +1,8 @@ +--- +title: Configuration 包使用说明 +description: 说明 GFramework.Core 的 Configuration 包、线程安全配置管理能力与核心接口。 +--- + # Configuration 包使用说明 ## 概述 diff --git a/docs/zh-CN/core/context.md b/docs/zh-CN/core/context.md index f905e2be..420910ff 100644 --- a/docs/zh-CN/core/context.md +++ b/docs/zh-CN/core/context.md @@ -1,3 +1,8 @@ +--- +title: Context +description: 说明 IArchitectureContext 与 ArchitectureContext 的统一上下文入口和当前推荐用法。 +--- + # Context `IArchitectureContext` 是框架的统一上下文入口。 diff --git a/docs/zh-CN/core/environment.md b/docs/zh-CN/core/environment.md index 26a0eb3b..673c5263 100644 --- a/docs/zh-CN/core/environment.md +++ b/docs/zh-CN/core/environment.md @@ -1,3 +1,8 @@ +--- +title: Environment 包使用说明 +description: 说明 GFramework.Core 的 Environment 包、运行时环境键值存储与核心接口。 +--- + # Environment 包使用说明 ## 概述 @@ -215,4 +220,4 @@ public class GoodExampleSystem : AbstractSystem - [`architecture`](./architecture.md) - 在架构中使用环境配置 - [`rule`](./rule.md) - 环境基类继承自 ContextAwareBase -- [`ioc`](./ioc.md) - 环境值可通过IoC容器管理 \ No newline at end of file +- [`ioc`](./ioc.md) - 环境值可通过IoC容器管理 diff --git a/docs/zh-CN/core/events.md b/docs/zh-CN/core/events.md index 3988741d..19840c37 100644 --- a/docs/zh-CN/core/events.md +++ b/docs/zh-CN/core/events.md @@ -1,3 +1,8 @@ +--- +title: Events +description: 说明 GFramework.Core.Events 的轻量广播模型、安装方式与常用事件入口。 +--- + # Events `GFramework.Core.Events` 是架构内的轻量广播层。它适合表达“某件事已经发生”的运行时信号、模块间松耦合通知， diff --git a/docs/zh-CN/core/extensions.md b/docs/zh-CN/core/extensions.md index a713d471..ad96e0d7 100644 --- a/docs/zh-CN/core/extensions.md +++ b/docs/zh-CN/core/extensions.md @@ -1,3 +1,8 @@ +--- +title: Extensions 包使用说明 +description: 说明 GFramework.Core.Extensions 常用扩展方法的分类、用途与访问入口。 +--- + # Extensions 包使用说明 ## 概述 @@ -549,4 +554,4 @@ public class AchievementSystem : AbstractSystem - [`events`](./events.md) - 事件注册和 Or 组合扩展 - [`model`](./model.md) - 模型获取扩展 - [`system`](./system.md) - 系统获取扩展 -- [`utility`](./utility.md) - 工具获取扩展 \ No newline at end of file +- [`utility`](./utility.md) - 工具获取扩展 diff --git a/docs/zh-CN/core/functional.md b/docs/zh-CN/core/functional.md index 8de4d837..f2e4e061 100644 --- a/docs/zh-CN/core/functional.md +++ b/docs/zh-CN/core/functional.md @@ -1,3 +1,8 @@ +--- +title: 函数式编程指南 +description: 说明 GFramework.Core 的 Option、Result 与函数式工具在业务代码中的用法。 +--- + # 函数式编程指南 ## 概述 diff --git a/docs/zh-CN/core/ioc.md b/docs/zh-CN/core/ioc.md index 4aa53e5e..d5c2ba57 100644 --- a/docs/zh-CN/core/ioc.md +++ b/docs/zh-CN/core/ioc.md @@ -1,3 +1,8 @@ +--- +title: IoC 包使用说明 +description: 说明 GFramework.Core 的 IoC 容器、依赖注入职责与核心类型。 +--- + # IoC 包使用说明 ## 概述 @@ -441,7 +446,7 @@ public class IocContainer ### 线程安全机制 -容器使用 [ReaderWriterLockSlim](xref:System.Threading.ReaderWriterLockSlim) 来确保线程安全操作，允许多个线程同时读取，但在写入时阻止其他线程访问。 +容器使用 `ReaderWriterLockSlim` 来确保线程安全操作，允许多个线程同时读取，但在写入时阻止其他线程访问。 ### 注册流程 @@ -848,4 +853,4 @@ protected override void OnInit() - [`architecture`](./architecture.md) - 使用 IoC 容器管理所有组件 - [`model`](./model.md) - Model 通过 IoC 容器注册和获取 - [`system`](./system.md) - System 通过 IoC 容器注册和获取 -- [`utility`](./utility.md) - Utility 通过 IoC 容器注册和获取 \ No newline at end of file +- [`utility`](./utility.md) - Utility 通过 IoC 容器注册和获取 diff --git a/docs/zh-CN/core/localization.md b/docs/zh-CN/core/localization.md index 03cb1120..30193b19 100644 --- a/docs/zh-CN/core/localization.md +++ b/docs/zh-CN/core/localization.md @@ -1,3 +1,8 @@ +--- +title: Localization 本地化系统 +description: 说明 GFramework.Core 本地化系统的核心接口、语言切换能力与使用场景。 +--- + # Localization 本地化系统 ## 概述 diff --git a/docs/zh-CN/core/logging.md b/docs/zh-CN/core/logging.md index 914a155d..719301f0 100644 --- a/docs/zh-CN/core/logging.md +++ b/docs/zh-CN/core/logging.md @@ -1,3 +1,8 @@ +--- +title: Logging +description: 说明 GFramework.Core.Logging 的日志接口、组合方式与常见使用入口。 +--- + # Logging `GFramework.Core.Logging` 是 Core runtime 的默认日志实现。只加载抽象层时，`LoggerFactoryResolver` 会退回 diff --git a/docs/zh-CN/core/model.md b/docs/zh-CN/core/model.md index d2cab7e5..545e085f 100644 --- a/docs/zh-CN/core/model.md +++ b/docs/zh-CN/core/model.md @@ -1,3 +1,8 @@ +--- +title: Model 包使用说明 +description: 说明 GFramework.Core.Model 的模型职责、基类结构与常见生命周期入口。 +--- + # Model 包使用说明 ## 概述 @@ -229,4 +234,4 @@ await architecture.InitializeAsync(); - [`property`](./property.md) - BindableProperty 用于定义可监听属性 - [`events`](./events.md) - Model 发送事件通知变化 - [`utility`](./utility.md) - Model 可以使用工具类 -- [`extensions`](./extensions.md) - 提供 GetModel 等扩展方法 \ No newline at end of file +- [`extensions`](./extensions.md) - 提供 GetModel 等扩展方法 diff --git a/docs/zh-CN/core/pause.md b/docs/zh-CN/core/pause.md index bb3e2dca..a4720896 100644 --- a/docs/zh-CN/core/pause.md +++ b/docs/zh-CN/core/pause.md @@ -1,3 +1,8 @@ +--- +title: 暂停管理系统使用说明 +description: 说明 GFramework.Core 暂停管理系统的栈模型、作用域与协作方式。 +--- + # 暂停管理系统使用说明 ## 概述 diff --git a/docs/zh-CN/core/pool.md b/docs/zh-CN/core/pool.md index f818dfa0..fd0ab7ff 100644 --- a/docs/zh-CN/core/pool.md +++ b/docs/zh-CN/core/pool.md @@ -1,3 +1,8 @@ +--- +title: 对象池系统 (Object Pool System) +description: 说明 GFramework.Core 对象池系统的核心组件、池化策略与生命周期管理。 +--- + # 对象池系统 (Object Pool System) ## 概述 diff --git a/docs/zh-CN/core/property.md b/docs/zh-CN/core/property.md index ab7d6451..9d79ba76 100644 --- a/docs/zh-CN/core/property.md +++ b/docs/zh-CN/core/property.md @@ -1,3 +1,8 @@ +--- +title: Property +description: 说明 GFramework.Core.Property 的可绑定属性模型、订阅方式与常见用法。 +--- + # Property `GFramework.Core.Property` 负责字段级响应式值。它最适合“一个字段变化就足以驱动视图或局部业务逻辑”的场景； diff --git a/docs/zh-CN/core/query.md b/docs/zh-CN/core/query.md index 43e31ab7..0ae3a6de 100644 --- a/docs/zh-CN/core/query.md +++ b/docs/zh-CN/core/query.md @@ -1,3 +1,8 @@ +--- +title: Query +description: 说明 GFramework.Core.Query 旧查询体系的兼容定位、可用基类与当前使用约束。 +--- + # Query 本页说明 `GFramework.Core.Query` 里的旧查询体系。 diff --git a/docs/zh-CN/core/rule.md b/docs/zh-CN/core/rule.md index 28b4c442..8b36cf0d 100644 --- a/docs/zh-CN/core/rule.md +++ b/docs/zh-CN/core/rule.md @@ -1,3 +1,8 @@ +--- +title: Rule 包使用说明 +description: 说明 GFramework.Core.Rule 中 IContextAware 规则接口与上下文访问约定。 +--- + # Rule 包使用说明 ## 概述 @@ -348,4 +353,4 @@ IArchitectureContext IContextAware.GetContext() - [`query`](./query.md) - Query 继承 `AbstractQuery` (实现 `IContextAware`) - [`model`](./model.md) - Model 继承 `AbstractModel` (实现 `IContextAware`) - [`system`](./system.md) - System 继承 `AbstractSystem` (实现 `IContextAware`) -- [`extensions`](./extensions.md) - 提供 `ContextAwareExtensions` 扩展方法 \ No newline at end of file +- [`extensions`](./extensions.md) - 提供 `ContextAwareExtensions` 扩展方法 diff --git a/docs/zh-CN/core/state-management.md b/docs/zh-CN/core/state-management.md index 4bd9f844..e1dedecf 100644 --- a/docs/zh-CN/core/state-management.md +++ b/docs/zh-CN/core/state-management.md @@ -1,3 +1,8 @@ +--- +title: State Management 包使用说明 +description: 说明 GFramework.Core.StateManagement 的 Store、Reducer 与状态容器用法。 +--- + # State Management 包使用说明 ## 概述 @@ -482,7 +487,7 @@ public partial class PlayerPanelController : IController ## 相关文档 -- [`property`](./property) - 字段级响应式属性 -- [`model`](./model) - Store 常见承载位置 -- [`events`](./events) - 组件间事件通信 -- [`state-machine-tutorial`](../tutorials/state-machine-tutorial) - 流程状态切换能力 +- [`property`](./property.md) - 字段级响应式属性 +- [`model`](./model.md) - Store 常见承载位置 +- [`events`](./events.md) - 组件间事件通信 +- [`state-machine-tutorial`](../tutorials/state-machine-tutorial.md) - 流程状态切换能力 diff --git a/docs/zh-CN/core/system.md b/docs/zh-CN/core/system.md index b5f685ad..8e3e3557 100644 --- a/docs/zh-CN/core/system.md +++ b/docs/zh-CN/core/system.md @@ -1,3 +1,8 @@ +--- +title: System 包使用说明 +description: 说明 GFramework.Core.System 的业务逻辑层职责、基类结构与协作方式。 +--- + # System 包使用说明 ## 概述 @@ -660,4 +665,4 @@ public class ParticleSystem : AbstractSystem - [`command`](./command.md) - System 中可以发送 Command - [`query`](./query.md) - System 中可以发送 Query - [`utility`](./utility.md) - System 可以使用 Utility -- [`architecture`](./architecture.md) - 在架构中注册 System \ No newline at end of file +- [`architecture`](./architecture.md) - 在架构中注册 System diff --git a/docs/zh-CN/core/utility.md b/docs/zh-CN/core/utility.md index 37f199ec..80d8bb15 100644 --- a/docs/zh-CN/core/utility.md +++ b/docs/zh-CN/core/utility.md @@ -1,3 +1,8 @@ +--- +title: Utility 包使用说明 +description: 说明 GFramework.Core.Utility 的工具组件定位、注册方式与使用场景。 +--- + # Utility 包使用说明 ## 概述