diff --git a/.agents/skills/_shared/DOCUMENTATION_STANDARDS.md b/.agents/skills/_shared/DOCUMENTATION_STANDARDS.md index 70678847..9019e200 100644 --- a/.agents/skills/_shared/DOCUMENTATION_STANDARDS.md +++ b/.agents/skills/_shared/DOCUMENTATION_STANDARDS.md @@ -40,6 +40,18 @@ 如果 `ai-libs/` 与当前源码或测试冲突，以当前仓库实现为准，并在文档里写明迁移或兼容边界。 +## 公开文档边界 + +- `README.md` 与 `docs/**` 面向框架使用者，不面向治理执行者。 +- 不要把 inventory、覆盖基线、恢复点、批处理阈值、review 线程、待补审计波次等内部治理信息写进公开页面。 +- XML、README、测试与 `ai-libs/` 证据可以驱动文档决策，但公开页面只能输出读者真正需要的内容： + - 模块边界 + - 最小接入路径 + - 推荐阅读顺序 + - 源码 / XML / API 的入口提示 +- 如果确实需要保留治理基线、盘点结果或后续治理计划，把它写到 `ai-plan/**` 或其他 contributor-only 记录里。 +- 当页面需要引用 XML 文档时，写“应优先查看哪些类型、命名空间或契约，以及为什么”，不要写覆盖数量、盘点日期或“已覆盖 / 未覆盖”状态。 + ## Markdown 规则 ### 泛型与 HTML 转义 @@ -83,6 +95,12 @@ description: 1-2 句话描述当前页面解决什么问题 3. 再补 API reference 4. 最后才补教程 +## 用户页检查点 + +- 用户读完页面后，应知道怎么采用、该看哪几个入口，而不是知道当前治理批次做到哪一轮。 +- 如果一段内容删掉日期、数量、基线、治理术语后就失去价值，它大概率不该出现在公开文档里。 +- 表格优先表达“何时看什么、解决什么问题”，不要表达“当前盘点覆盖到哪里”。 + ## 验证清单 - [ ] frontmatter 正确 diff --git a/.agents/skills/gframework-doc-refresh/SKILL.md b/.agents/skills/gframework-doc-refresh/SKILL.md index 6212d6f8..e033d8ec 100644 --- a/.agents/skills/gframework-doc-refresh/SKILL.md +++ b/.agents/skills/gframework-doc-refresh/SKILL.md @@ -173,6 +173,10 @@ Use this exact priority: - Prefer correcting the adoption path over expanding page count. - Do not copy wording from outdated docs just to keep page volume. +- Public docs must stay reader-facing. Do not write inventory, coverage baseline, recovery-point, batch-metric, review + backlog, or audit-wave wording into `README.md` or `docs/**`. +- If XML or audit evidence is relevant, translate it into reader guidance such as “which types to inspect first” or + “which entry points define the contract”, instead of exposing counts, dates, or governance status. - Escape generics outside code blocks. - Keep internal links real and current. - Mark code blocks with explicit languages. diff --git a/AGENTS.md b/AGENTS.md index 625a569d..082bc7ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -312,6 +312,11 @@ bash scripts/validate-csharp-naming.sh - Update the relevant `README.md` or `docs/` page when behavior, setup steps, architecture guidance, or user-facing examples change. +- Public documentation under `README.md` and `docs/**` MUST stay reader-facing. Do not publish governance-only content + such as inventory tables, coverage baselines, review queues, batch metrics, recovery points, trace summaries, or + “this still needs a later audit wave” notes in those user-facing pages. +- Governance-only material such as XML audit snapshots, documentation remediation baselines, backlog status, and + recovery metadata belongs in `ai-plan/**` or other contributor-only artifacts, not in public docs. - Treat `ai-libs/` as a read-only third-party source reference area. - Code under `ai-libs/**` exists for comparison, tracing, design study, and behavior verification; do not modify it unless the user explicitly asks to sync or update that third-party snapshot. @@ -323,6 +328,9 @@ bash scripts/validate-csharp-naming.sh - The main documentation site lives under `docs/`, with Chinese content under `docs/zh-CN/`. - Keep code samples, package names, and command examples aligned with the current repository state. - Prefer documenting behavior and design intent, not only API surface. +- When a public page references XML docs or API coverage, convert that evidence into reader-facing guidance: explain + which types, namespaces, or entry points readers should inspect and why, instead of exposing audit counts or + governance terminology. - When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the corresponding user-facing integration documentation in `docs/zh-CN/` in the same change. - For integration-oriented features such as the AI-First config system, documentation MUST cover: diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md new file mode 100644 index 00000000..2f1ff935 --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md @@ -0,0 +1,133 @@ +# Documentation Full Coverage Governance Status History RP-023 To RP-025 + +以下内容从 active tracking 中迁出，用于保留 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-023` 到 +`DOCUMENTATION-FULL-COVERAGE-GOV-RP-025` 的批处理状态、验证细节与恢复背景。默认 `boot` 只需要读取 active +tracking 中的最新摘要；若需要追溯 `2026-04-23` 到 `2026-04-24` 的治理细节，再回到本归档文件。 + +## 迁出的状态摘要 + +- `2026-04-23` 基于 PR `#272` 的 review follow-up 已完成： + - 为 `docs/zh-CN/game/data.md` 补充 `UnifiedSettingsDataRepository` 的统一文件布局示例 + - 为 `GFramework.Godot.SourceGenerators/README.md` 补充手写 `_Ready()` / `_ExitTree()` 时显式调用生成方法的最小样例 + - 将过长的 active tracking / trace 瘦身，并把历史摘要迁回 `archive/` +- `2026-04-23` 使用 `$gframework-pr-review` 重新抓取 PR `#272` 后，确认 latest-head review 当前仍有 1 条 + Greptile open thread，定位到 `docs/zh-CN/godot/setting.md:75` 的 inline code 误写成 + `SettingsModel<ISettingsDataRepository>`。 +- 结合当前 PR 已改动的 `docs/zh-CN/godot/storage.md` 做同类巡检后，确认 `SaveRepository<TSaveData>` + 也会在 VitePress code span 中按字面量渲染；两处现已在本地统一改为真实泛型写法。 +- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对 + `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 执行同类模式巡检，确认剩余热点仅位于 + `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处。 +- 上述 8 处 inline code 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 已统一改为真实 + 泛型写法，避免在 VitePress 中显示字面量 HTML entity。 +- `2026-04-23` 根据本轮使用反馈，已为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 + `.agents/skills/README.md` 补充数字速记阈值语义： + - `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止” + - `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止” + - `75 | 2000` 仅作为可理解的 OR 写法保留，不再作为推荐写法，以避免与 shell pipe 混淆 +- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对 + `docs/zh-CN/getting-started/index.md`、`core/index.md`、`game/index.md`、`source-generators/index.md`、 + `api-reference/index.md`、`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md` + 做导航可达性修复，把仓库 README / 根 README 裸路径统一改为指向 GitHub `main` 分支的可点击链接。 +- 该批次不改变文档语义，只收口 docs 站点中的入口可达性；适合继续作为小步快跑的低风险治理模式。 +- `2026-04-23` 在同一基线下继续收口第二批专题页导航热点，已将 `core/cqrs.md`、`ecs/arch.md`、 + `abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 和 6 个 + `source-generators/*.md` 专题页里的 README 裸路径统一改为 GitHub `main` blob 外链。 +- 截至提交 `8a11720`（`2026-04-23T21:01:28+08:00`），当前分支相对 `origin/main`（`aa879d2`）的累计 diff + 为 `24` 个文件、`264` 行，仍低于 `$gframework-batch-boot 75` 的停止阈值；但剩余命中已主要是正文语义性提及，不再适合作为同类批处理。 +- 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地 + 文件缺陷。 +- `2026-04-24` 根据用户反馈完成一轮“公开文档边界”治理，并继续按 `$gframework-batch-boot 75` 向前推进： + - 在 `AGENTS.md`、`.agents/skills/_shared/DOCUMENTATION_STANDARDS.md` 与 + `.agents/skills/gframework-doc-refresh/SKILL.md` 中新增硬约束，明确禁止把 inventory、覆盖基线、恢复点、 + review backlog、治理批次等 contributor-only 内容写进 `README.md` 与 `docs/**` + - 将 `docs/zh-CN/core/index.md`、`core/cqrs.md`、`game/index.md`、 + `abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`、`ecs/index.md`、 + `ecs/arch.md`、`abstractions/ecs-arch-abstractions.md` 中的 XML 覆盖表述改写为面向读者的“源码阅读入口” + - 顺手收口 `api-reference/index.md`、`contributor/development-environment.md` 与 + `source-generators/*.md` 中的内部口吻用语，例如 `landing page`、`验证基线`、`目标类型基线` + - focused validator 已覆盖本轮触达的 `13` 个公开文档页面并全部通过；站点构建 `cd docs && bun run build` + 已通过，仅保留既有大 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` 的停止阈值。 +- `2026-04-24` 继续在同一 stop condition 下执行第三个低风险批次，集中清理 `docs/zh-CN` 其余“完全缺 frontmatter”的页面： + - 已为 `best-practices/*.md` 中缺口页、`contributing.md`、`faq.md`、`game/config-system.md`、 + `getting-started/*.md`、`godot/coroutine.md`、6 个 `source-generators/*.md`、`troubleshooting.md`、 + `tutorials/advanced-patterns.md`、`tutorials/basic/index.md` 与 `tutorials/index.md` 补齐 frontmatter + - 在同批次内修复 `best-practices/multiplayer.md` 的未闭合代码块、`source-generators/*.md` 中缺少 `.md` + 后缀的相对链接，以及 `troubleshooting.md` 里 3 处目录索引死链 + - 当前 `docs/zh-CN` 已不存在“完全缺 frontmatter”的页面；剩余 metadata 热点只剩 + `docs/zh-CN/index.md` 与 `docs/zh-CN/tutorials/basic/01-07.md` 共 `8` 个“已有 frontmatter 但缺 title / + description”的页面 + - 本批次落地前，当前分支相对 `origin/main` 的累计 branch diff 为 `39` 个文件；连同本轮工作和 tracking / trace + 更新后，预计提交后累计 diff 约为 `63` 个文件，仍低于 `$gframework-batch-boot 75` 的停止阈值 + +## 迁出的验证记录 + +- `2026-04-24` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN` + - 结果：失败；暴露出仓库既有的 `53` 个历史文档问题（大量缺少 frontmatter、既有坏链与未标语言代码块），不由本轮改动引入，因此本轮改用 focused validator 证明任务级结果。 +- `2026-04-24` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core` + - 结果：通过；确认 `Core` 模块的 README、landing、topic 与 fallback docs 入口仍可解析。 +- `2026-04-24` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game` + - 结果：通过；确认 `Game` 模块的 README、landing、topic 与 fallback docs 入口仍可解析。 +- `2026-04-24` focused validator（逐个校验本轮触达页面） + - 结果：通过；`docs/zh-CN/abstractions/core-abstractions.md`、 + `abstractions/ecs-arch-abstractions.md`、`abstractions/game-abstractions.md`、 + `api-reference/index.md`、`contributor/development-environment.md`、`core/cqrs.md`、`core/index.md`、 + `ecs/arch.md`、`ecs/index.md`、`game/index.md`、 + `source-generators/bind-node-signal-generator.md`、 + `source-generators/cqrs-handler-registry-generator.md`、 + `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-24` focused validator（逐个校验第三批触达的 `22` 个页面） + - 结果：通过；frontmatter、真实坏链与未闭合代码块问题均已修复，剩余仅为 `best-practices/architecture-patterns.md`、 + `best-practices/index.md`、`contributing.md`、`troubleshooting.md` 与 `tutorials/index.md` 的既有代码块语言 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 渲染问题。 +- `2026-04-23` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' GFramework.Godot.SourceGenerators/README.md GFramework.Godot/README.md README.md docs/zh-CN/api-reference/index.md docs/zh-CN/game/data.md docs/zh-CN/game/serialization.md docs/zh-CN/game/setting.md docs/zh-CN/game/storage.md docs/zh-CN/godot/setting.md docs/zh-CN/godot/storage.md docs/zh-CN/source-generators/index.md` + - 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。 +- `2026-04-23` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'` + - 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。 +- `2026-04-23` `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md` 与 `sed -n '1,220p' .agents/skills/README.md` + - 结果：确认原文仅描述自然语言 stop condition，没有定义数字速记或多阈值 OR 语义；现已补齐。 +- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` + - 结果：确认 landing / API 导航页仍有一批裸路径仓库入口；本轮已先修复 `getting-started`、`core`、`game`、 + `source-generators`、`api-reference` 与两个 abstractions 页面。 +- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` + - 结果：定位第二批专题页导航热点，已修复 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、 + `game/scene.md`、`game/ui.md` 以及 6 个 `source-generators/*.md` 页面。 +- `2026-04-23` `bun run build`（工作目录：`docs/`） + - 结果：通过；仓库 README 外链改为 GitHub `main` blob 后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 + +## 迁出的下一步 + +1. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8` + 个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。 +2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖 + 常见分支阈值场景。 +3. 若后续分支继续调整 `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`、 + `docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。 diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md new file mode 100644 index 00000000..d10c2e92 --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md @@ -0,0 +1,167 @@ +# Documentation Full Coverage Governance Trace History RP-023 To RP-025 + +以下内容从 active trace 中迁出，用于保留 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-023` 到 +`DOCUMENTATION-FULL-COVERAGE-GOV-RP-025` 的执行时间线、关键决策与主要验证结果。默认 `boot` 只需要读取 +active trace 中的最新恢复点；若需要追溯 `2026-04-23` 到 `2026-04-24` 的批处理执行顺序，再回到本归档文件。 + +## 2026-04-24 + +### 当前恢复点：RP-025 + +- 继续沿用 `$gframework-batch-boot 75`，基线保持 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）。 +- 本轮目标从“继续治理公开文档边界”切换为“清空 `docs/zh-CN` 中仍然完全缺 frontmatter 的页面，同时把触达页暴露的真实格式错误一并收口”。 +- 本轮执行的修复： + - 为 `best-practices`、`getting-started`、`source-generators`、`tutorials` 等目录下共 `22` 个页面补齐 + `title` / `description` frontmatter + - 修复 `docs/zh-CN/best-practices/multiplayer.md` 末尾缺失的代码块闭合符 + - 修复 `docs/zh-CN/source-generators/*.md` 与 `docs/zh-CN/troubleshooting.md` 中一组缺少 `.md` 后缀或目录索引写法不兼容当前 validator 的站内链接 + +### 当前决策（RP-025） + +- 对文档批处理，优先选择“元数据缺口 + 顺手修复真实结构错误”的组合，而不扩成正文语义刷新或大规模 code fence language 治理。 +- 当 focused validator 暴露的是触达页上的真实错误（如坏链、未闭合代码块）时，同批次直接收口；仅把纯 warning 留给下一轮专门治理。 +- 本轮结束时，`docs/zh-CN` 已没有“完全缺 frontmatter”的页面；下一批最稳定的切片是 `docs/zh-CN/index.md` 与 + `docs/zh-CN/tutorials/basic/01-07.md` 这 `8` 个“已有 frontmatter 但缺 `title` / `description`”的页面。 +- 当前已提交分支 diff 仍为 `39` 个文件；将本轮工作连同 tracking / trace 提交后，预计累计 branch diff 约为 `63` + 个文件，仍低于 `$gframework-batch-boot 75` 的停止阈值。 + +### 当前验证（RP-025） + +- frontmatter 缺口巡检： + - `for f in $(find docs/zh-CN -type f -name '*.md' | sort); do if ! head -n 5 "$f" | grep -q '^---$'; then echo "$f"; fi; done` + - 结果：本轮前命中 `22` 个页面，当前已全部补齐。 +- focused validator： + - 逐个校验本轮触达的 `22` 个页面 + - 结果：通过；只剩 `best-practices/architecture-patterns.md`、`best-practices/index.md`、`contributing.md`、 + `troubleshooting.md` 与 `tutorials/index.md` 的既有代码块语言 warning。 +- 站点构建： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；仅保留既有大 chunk warning。 +- 后续候选扫描： + - `python3 - <<'PY' ...`（扫描已有 frontmatter 但缺 `title` / `description` 的页面） + - 结果：命中 `docs/zh-CN/index.md` 与 `docs/zh-CN/tutorials/basic/01-07.md` 共 `8` 个页面，可作为下一批 metadata 修复入口。 + +### 下一步 + +1. 继续执行 `$gframework-batch-boot 75` 时，优先补齐 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 的 + `title` / `description` 缺口。 +2. 若仍有余量，再按目录收口 `best-practices`、`contributing`、`troubleshooting`、`tutorials/index.md` + 的代码块语言 warning，而不是跨全站混做。 + +### 当前恢复点：RP-024 + +- 根据用户反馈，将本轮目标重定义为“清理公开文档中的治理盘点式内容，并把同类约束补进仓库规范与 doc-refresh skill”。 +- 用户随后补充明确使用 `$gframework-batch-boot 75`，因此继续沿用 `origin/main` 作为固定基线，并把 `75` changed + files 作为主停止条件。 +- 本轮执行的修复： + - 在 `AGENTS.md`、`.agents/skills/_shared/DOCUMENTATION_STANDARDS.md` 与 + `.agents/skills/gframework-doc-refresh/SKILL.md` 中新增公开文档边界规则，禁止把 inventory、覆盖基线、 + 恢复点、review backlog 和治理批次写入 `README.md` 与 `docs/**` + - 将 `docs/zh-CN/core/index.md`、`core/cqrs.md`、`game/index.md`、 + `abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`、`ecs/index.md`、 + `ecs/arch.md`、`abstractions/ecs-arch-abstractions.md` 的 XML 覆盖 / inventory 段落改写成读者导向的源码阅读入口 + - 继续收口 `api-reference/index.md`、`contributor/development-environment.md` 与 + `source-generators/*.md` 中的内部术语，例如 `landing page`、`验证基线`、`目标类型基线` + - 为 `docs/zh-CN/contributor/development-environment.md` 补齐 frontmatter，使其满足当前文档规范 + +### 当前决策（RP-024） + +- 公开文档只承载采用路径、阅读入口、模块边界和可验证示例；治理盘点、覆盖状态和恢复点一律留在 `ai-plan/**`。 +- 当 XML 治理结果需要体现在公开文档里时，只输出“优先看哪些类型 / 命名空间 / 契约以及为什么”，不输出计数、日期或状态表。 +- `$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） + +- 同类治理内容巡检： + - `rg -n 'XML Inventory|XML 覆盖基线|XML 状态|基线状态|盘点|治理优先级|审计入口|覆盖基线|恢复点|验证基线|目标类型基线|目标字段基线|类型审计|契约审计|源码 / API' docs/zh-CN README.md -g '*.md'` + - 结果：公开页已无同类命中；剩余 `inventory` 命中仅来自正常代码示例变量名。 +- skill 自检： + - `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core` + - `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game` + - 结果：均通过；代表模块的 README / docs 入口映射仍有效。 +- 全量 docs 校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN` + - 结果：失败；暴露 `53` 个仓库既有历史问题（缺少 frontmatter、坏链、未标语言代码块），不属于本轮改动。 +- focused validator： + - 逐个校验本轮触达的 `13` 个公开文档页面 + - 结果：全部通过。 +- 站点构建： + - `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` 时，优先按目录做历史 frontmatter / code fence language / 坏链修复，而不是把不同风格的文档语义刷新混成一批。 +2. 当前批次在 `core` 目录已经不再是“同样机械”的模式，后续若继续应转向其他目录或专门做代码块语言标记治理。 + +## 2026-04-23 + +### 当前恢复点：RP-023 + +- 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。 +- 本轮目标定义为“继续沿用上一批的 GitHub 外链策略，收口专题页里的裸路径 README 入口”。 +- 本轮执行的修复： + - 将 `docs/zh-CN/core/cqrs.md` 与 `ecs/arch.md` 的仓库 README 入口改为 GitHub `main` blob 外链 + - 将 `docs/zh-CN/abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 的回跳 README 入口改为可点击链接 + - 将 `docs/zh-CN/source-generators/priority-generator.md`、`context-aware-generator.md`、 + `bind-node-signal-generator.md`、`godot-project-generator.md`、`get-node-generator.md`、 + `auto-register-exported-collections-generator.md` 的推荐阅读 README 入口改为可点击链接 + - 同步更新 active tracking / trace，记录第二批导航治理与新的恢复点 + +### 当前决策（RP-023） + +- 继续使用 `origin/main` 作为 `$gframework-batch-boot 75` 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。 +- 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。 +- 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。 +- 当 docs 页需要跳转到 `docs/` 外部的 README 时，使用 GitHub `main` 分支 blob 外链，而不是跨出 `docs/` 根目录的相对路径。 +- 第二批继续沿用同一外链策略，避免在同一 docs surface 中混用“裸路径 / 相对死链 / GitHub 外链”三套入口风格。 + +### 当前验证（RP-023） + +- 导航热点巡检： + - `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` + - 结果：命中 landing / API 导航页中的裸路径仓库入口，已按本轮批次收口 7 个页面。 +- 第二批专题页巡检： + - `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` + - 结果：命中 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、`game/scene.md`、 + `game/ui.md` 与 6 个 `source-generators/*.md` 专题页，均已修复。 +- 构建校验： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；将仓库 README 跳转改为 GitHub `main` blob 外链后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 +- 当前阈值状态： + - `git diff --name-only origin/main...HEAD | wc -l` => `24` + - `git diff --numstat origin/main...HEAD` 汇总 => `264` changed lines + - 结论：尚未接近 `75` 文件阈值，但剩余命中主要是正文语义性提及，当前批次在低风险模板化导航治理上可先收口。 + +### 归档摘要（RP-022） + +- 为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 `.agents/skills/README.md` 补齐数字速记 stop condition 语义。 +- 明确 `$gframework-batch-boot 75` / `75 2000` 默认绑定 `origin/main` 累计 diff 口径。 +- 完成第一批 landing / API 导航页 README 外链治理，并通过 `docs/` 站点构建。 + +### 归档指针 + +- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md` +- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md` +- `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md` + +### 下一步 + +1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。 +2. 若继续执行文档治理批处理，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接热点，而不是扩成跨模块大波次。 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 c769ae40..1339356a 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,11 +12,12 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-023` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-026` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 保持 landing page / API 导航页中的仓库 README 入口可点击，避免读者在 docs 站点里遇到裸路径文本 - - 继续按 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险导航 / 渲染热点 + - 收口 PR `#282` 的 latest-head review follow-up，保持 active tracking / trace 只承载当前恢复入口 + - 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明 + - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险 metadata 缺口、坏链与 Markdown 结构问题 - 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述 - 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性 - 保持 active tracking / trace 只承载当前恢复入口，把阶段细节留在 `archive/` @@ -24,49 +25,27 @@ ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 +- `2026-04-24` 使用 `$gframework-pr-review` 抓取 PR `#282` 后，确认 latest head commit + `982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread；4 条建议均已在本地复核并纳入当前恢复点。 +- 本轮 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` 链接写法 - `Game` persistence docs surface 当前以 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 作为最小巡检集合；若后续 README、runtime public API 或 `PersistenceTests` 变动，应优先复核这一组页面。 - `Godot` runtime 与 generator 入口当前以 `GFramework.Godot/README.md`、 `GFramework.Godot.SourceGenerators/README.md`、`docs/zh-CN/godot/index.md`、 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/tutorials/godot-integration.md` 维持统一 owner / adoption path。 -- `2026-04-23` 基于 PR `#272` 的 review follow-up 已完成： - - 为 `docs/zh-CN/game/data.md` 补充 `UnifiedSettingsDataRepository` 的统一文件布局示例 - - 为 `GFramework.Godot.SourceGenerators/README.md` 补充手写 `_Ready()` / `_ExitTree()` 时显式调用生成方法的最小样例 - - 将过长的 active tracking / trace 瘦身，并把历史摘要迁回 `archive/` -- `2026-04-23` 使用 `$gframework-pr-review` 重新抓取 PR `#272` 后，确认 latest-head review 当前仍有 1 条 - Greptile open thread，定位到 `docs/zh-CN/godot/setting.md:75` 的 inline code 误写成 - `SettingsModel<ISettingsDataRepository>`。 -- 结合当前 PR 已改动的 `docs/zh-CN/godot/storage.md` 做同类巡检后，确认 `SaveRepository<TSaveData>` - 也会在 VitePress code span 中按字面量渲染；两处现已在本地统一改为真实泛型写法。 -- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对 - `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 执行同类模式巡检，确认剩余热点仅位于 - `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处。 -- 上述 8 处 inline code 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 已统一改为真实 - 泛型写法，避免在 VitePress 中显示字面量 HTML entity。 -- `2026-04-23` 根据本轮使用反馈，已为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 - `.agents/skills/README.md` 补充数字速记阈值语义： - - `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止” - - `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止” - - `75 | 2000` 仅作为可理解的 OR 写法保留，不再作为推荐写法，以避免与 shell pipe 混淆 -- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对 - `docs/zh-CN/getting-started/index.md`、`core/index.md`、`game/index.md`、`source-generators/index.md`、 - `api-reference/index.md`、`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md` - 做导航可达性修复，把仓库 README / 根 README 裸路径统一改为指向 GitHub `main` 分支的可点击链接。 -- 该批次不改变文档语义，只收口 docs 站点中的入口可达性；适合继续作为小步快跑的低风险治理模式。 -- `2026-04-23` 在同一基线下继续收口第二批专题页导航热点，已将 `core/cqrs.md`、`ecs/arch.md`、 - `abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 和 6 个 - `source-generators/*.md` 专题页里的 README 裸路径统一改为 GitHub `main` blob 外链。 -- 截至提交 `8a11720`（`2026-04-23T21:01:28+08:00`），当前分支相对 `origin/main`（`aa879d2`）的累计 diff - 为 `24` 个文件、`264` 行，仍低于 `$gframework-batch-boot 75` 的停止阈值；但剩余命中已主要是正文语义性提及，不再适合作为同类批处理。 -- 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地 - 文件缺陷。 +- `2026-04-23` 到 `2026-04-24` 的批次细节、验证日志与旧恢复建议已迁入： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md` ## 当前风险 -- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理仍以“类型声明级基线”为主，不等于成员级契约全审计。 +- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理证据仍主要来自类型与入口级阅读，不等于成员级契约全审计；这类治理状态只应保留在 `ai-plan/**`，不应再暴露到公开文档。 - `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发 `MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。 - 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。 +- PR `#282` 的 `Title check` 仍可能提示标题过泛；这是 GitHub PR 元数据问题，不属于本地文件缺陷。 ## 归档指针 @@ -74,34 +53,27 @@ `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md` - 阶段状态归档（`RP-001` 到 `RP-016`）： `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md` +- 阶段状态归档（`RP-023` 到 `RP-025`）： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md` - 时间线归档（`RP-001` 到 `RP-016`）： `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md` +- 时间线归档（`RP-023` 到 `RP-025`）： + `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md` ## 最新验证 -- `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 渲染问题。 -- `2026-04-23` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' GFramework.Godot.SourceGenerators/README.md GFramework.Godot/README.md README.md docs/zh-CN/api-reference/index.md docs/zh-CN/game/data.md docs/zh-CN/game/serialization.md docs/zh-CN/game/setting.md docs/zh-CN/game/storage.md docs/zh-CN/godot/setting.md docs/zh-CN/godot/storage.md docs/zh-CN/source-generators/index.md` - - 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。 -- `2026-04-23` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'` - - 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。 -- `2026-04-23` `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md` 与 `sed -n '1,220p' .agents/skills/README.md` - - 结果：确认原文仅描述自然语言 stop condition，没有定义数字速记或多阈值 OR 语义；现已补齐。 -- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` - - 结果：确认 landing / API 导航页仍有一批裸路径仓库入口；本轮已先修复 `getting-started`、`core`、`game`、 - `source-generators`、`api-reference` 与两个 abstractions 页面。 -- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` - - 结果：定位第二批专题页导航热点，已修复 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、 - `game/scene.md`、`game/ui.md` 以及 6 个 `source-generators/*.md` 页面。 -- `2026-04-23` `bun run build`（工作目录：`docs/`） - - 结果：通过；仓库 README 外链改为 GitHub `main` blob 后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 +- `2026-04-24` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json` + - 结果：通过；PR `#282` 处于 `OPEN`，latest head commit 有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread，测试汇总为 `2156 passed`，仅剩 `Title check` 的 inconclusive PR 元数据提示。 +- `2026-04-24` `rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(? `24` - - `git diff --numstat origin/main...HEAD` 汇总 => `264` changed lines - - 结论：尚未接近 `75` 文件阈值，但剩余命中主要是正文语义性提及，当前批次在低风险模板化导航治理上可先收口。 - -### 归档摘要（RP-022） - -- 为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 `.agents/skills/README.md` 补齐数字速记 stop condition 语义。 -- 明确 `$gframework-batch-boot 75` / `75 2000` 默认绑定 `origin/main` 累计 diff 口径。 -- 完成第一批 landing / API 导航页 README 外链治理，并通过 `docs/` 站点构建。 + - 结果：通过；本轮文档与 `ai-plan` 调整后站点仍可正常构建，仅保留既有大 chunk warning。 ### 归档指针 - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md` - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md` +- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md` - `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md` +- `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md` ### 下一步 -1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。 -2. 若继续执行文档治理批处理，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接热点，而不是扩成跨模块大波次。 +1. 推送当前 follow-up commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。 +2. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8` 个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。 diff --git a/docs/zh-CN/abstractions/core-abstractions.md b/docs/zh-CN/abstractions/core-abstractions.md index 5f3398b8..153a5729 100644 --- a/docs/zh-CN/abstractions/core-abstractions.md +++ b/docs/zh-CN/abstractions/core-abstractions.md @@ -1,6 +1,6 @@ --- title: Core Abstractions -description: GFramework.Core.Abstractions 的契约边界、包关系与 XML 阅读重点。 +description: GFramework.Core.Abstractions 的契约边界、包关系与源码阅读重点。 --- # Core Abstractions @@ -70,29 +70,28 @@ public sealed class DiagnosticsFeature ## XML 阅读重点 -如果你在做契约审计、采用设计或扩展适配，优先核对这些类型族的 XML 文档： +如果你在做契约确认、采用设计或扩展适配，优先核对这些类型族的 XML 文档： - 架构与模块入口：`IArchitecture`、`IArchitectureContext`、`IServiceModule` - 运行时基础设施：`IIocContainer`、`ILogger`、`IResourceManager`、`IConfigurationManager` - 状态与并发能力：`IStateMachine`、`IStore`、`IAsyncKeyLockManager`、`ITimeProvider` - 迁移与组合边界：`ICommandExecutor`、`IQueryExecutor`、`ICqrsRuntime` -## XML 覆盖基线 +## 契约族阅读入口 -下面这份 inventory 记录的是 `2026-04-22` 对 `GFramework.Core.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 / -内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常与生命周期说明仍需要后续波次继续细化。 +如果你要回到源码 XML 文档确认契约，请优先看下面这些族群： -| 契约族 | 基线状态 | 代表类型 | 阅读重点 | -| --- | --- | --- | --- | -| `Architectures/` | `12/12` 个类型声明已带 XML 注释 | `IArchitecture`、`IArchitectureContext`、`IArchitectureServices`、`IServiceModule` | 看架构上下文、服务访问面与模块安装 / 生命周期约束 | -| `Lifecycle/` `Registries/` | `8/8` 个类型声明已带 XML 注释 | `ILifecycle`、`IAsyncInitializable`、`IRegistry`、`KeyValueRegistryBase` | 看初始化 / 销毁阶段和注册表抽象边界 | -| `Command/` `Query/` `Cqrs/` | `10/10` 个类型声明已带 XML 注释 | `ICommandExecutor`、`IAsyncCommand`、`IQueryExecutor`、`ICqrsRuntime` | 看旧命令 / 查询接口与新请求模型之间的兼容和迁移边界 | -| `Events/` `Property/` | `10/10` 个类型声明已带 XML 注释 | `IEventBus`、`IEventFilter`、`IBindableProperty`、`IReadonlyBindableProperty` | 看事件传播、过滤、解绑对象和属性订阅语义 | -| `State/` `StateManagement/` | `15/15` 个类型声明已带 XML 注释 | `IStateMachine`、`IAsyncState`、`IStore`、`IStoreMiddleware` | 看状态机契约与 Store 的 reducer / middleware / diagnostics 边界 | -| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `17/17` 个类型声明已带 XML 注释 | `IYieldInstruction`、`ICoroutineStatistics`、`ITimeProvider`、`IPauseStackManager`、`IAsyncKeyLockManager` | 看调度模型、时间源、暂停栈和异步锁契约 | -| `Resource/` `Pool/` `Logging/` `Localization/` | `27/27` 个类型声明已带 XML 注释 | `IResourceManager`、`IObjectPoolSystem`、`ILogger`、`IStructuredLogger`、`ILocalizationManager` | 看资源 / 池化 / 日志 / 本地化这些基础设施的宿主责任 | -| `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `7/7` 个类型声明已带 XML 注释 | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom`、`ISerializer`、`IStorage`、`IVersioned` | 看配置、环境、序列化和持久化边界，以及谁负责具体实现 | -| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `19/19` 个类型声明已带 XML 注释 | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` | 看基础角色接口、辅助值对象和架构属性键的复用方式 | +| 契约族 | 代表类型 | 建议先确认什么 | +| --- | --- | --- | +| `Architectures/` | `IArchitecture`、`IArchitectureContext`、`IArchitectureServices`、`IServiceModule` | 架构上下文、服务访问面与模块安装 / 生命周期约束 | +| `Lifecycle/` `Registries/` | `ILifecycle`、`IAsyncInitializable`、`IRegistry`、`KeyValueRegistryBase` | 初始化 / 销毁阶段和注册表抽象边界 | +| `Command/` `Query/` `Cqrs/` | `ICommandExecutor`、`IAsyncCommand`、`IQueryExecutor`、`ICqrsRuntime` | 旧命令 / 查询接口与新请求模型之间的兼容和迁移边界 | +| `Events/` `Property/` | `IEventBus`、`IEventFilter`、`IBindableProperty`、`IReadonlyBindableProperty` | 事件传播、过滤、解绑对象和属性订阅语义 | +| `State/` `StateManagement/` | `IStateMachine`、`IAsyncState`、`IStore`、`IStoreMiddleware` | 状态机契约与 Store 的 reducer / middleware / diagnostics 边界 | +| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `IYieldInstruction`、`ICoroutineStatistics`、`ITimeProvider`、`IPauseStackManager`、`IAsyncKeyLockManager` | 调度模型、时间源、暂停栈和异步锁契约 | +| `Resource/` `Pool/` `Logging/` `Localization/` | `IResourceManager`、`IObjectPoolSystem`、`ILogger`、`IStructuredLogger`、`ILocalizationManager` | 资源 / 池化 / 日志 / 本地化这些基础设施的宿主责任 | +| `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom`、`ISerializer`、`IStorage`、`IVersioned` | 配置、环境、序列化和持久化边界，以及谁负责具体实现 | +| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` | 基础角色接口、辅助值对象和架构属性键的复用方式 | ## 阅读顺序 diff --git a/docs/zh-CN/abstractions/ecs-arch-abstractions.md b/docs/zh-CN/abstractions/ecs-arch-abstractions.md index 72c631d4..808eda67 100644 --- a/docs/zh-CN/abstractions/ecs-arch-abstractions.md +++ b/docs/zh-CN/abstractions/ecs-arch-abstractions.md @@ -32,13 +32,13 @@ description: GFramework.Ecs.Arch.Abstractions 的契约边界、包关系和最 | `IArchSystemAdapter` | 让 ECS 系统适配到 `ISystem` 生命周期 | | `ArchOptions` | 承载 `WorldCapacity`、`EnableStatistics`、`Priority` 等配置 | -## 类型族级 XML Inventory +## 契约阅读入口 -| 类型族 | 代表类型 | XML 状态 | 阅读重点 | -| --- | --- | --- | --- | -| 模块契约 | `IArchEcsModule` | 已覆盖 | 统一更新入口、宿主循环边界 | -| 系统契约 | `IArchSystemAdapter` | 已覆盖 | 只依赖更新接口而不绑定默认 runtime | -| 配置对象 | `ArchOptions` | 已覆盖 | 共享配置字段与跨程序集采用边界 | +| 类型族 | 代表类型 | 建议先确认什么 | +| --- | --- | --- | +| 模块契约 | `IArchEcsModule` | 统一更新入口、宿主循环边界 | +| 系统契约 | `IArchSystemAdapter` | 只依赖更新接口而不绑定默认 runtime | +| 配置对象 | `ArchOptions` | 共享配置字段与跨程序集采用边界 | ## 最小接入路径 diff --git a/docs/zh-CN/abstractions/game-abstractions.md b/docs/zh-CN/abstractions/game-abstractions.md index a6f14437..532d1689 100644 --- a/docs/zh-CN/abstractions/game-abstractions.md +++ b/docs/zh-CN/abstractions/game-abstractions.md @@ -1,6 +1,6 @@ --- title: Game Abstractions -description: GFramework.Game.Abstractions 的契约边界、包关系与 XML 阅读重点。 +description: GFramework.Game.Abstractions 的契约边界、包关系与源码阅读重点。 --- # Game Abstractions @@ -37,19 +37,18 @@ description: GFramework.Game.Abstractions 的契约边界、包关系与 XML 阅 | `Routing/` | `IRoute`、`IRouteContext`、`IRouteGuard`，作为 Scene / UI 共享的路由基础约定 | | `Storage/` `Asset/` `Enums/` | 文件存储角色、资源注册表，以及转场 / UI 层级 / 输入动作等跨层枚举 | -## XML 覆盖基线 +## 契约族阅读入口 -下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 / -内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常和生命周期说明仍需要后续 API 波次继续细化。 +如果你要回到源码 XML 文档确认契约，请优先看下面这些族群： -| 契约族 | 基线状态 | 代表类型 | 阅读重点 | -| --- | --- | --- | --- | -| `Config/` | `7/7` 个类型声明已带 XML 注释 | `IConfigLoader`、`IConfigRegistry`、`IConfigTable`、`ConfigLoadException` | 看配置表注册、只读访问和失败诊断边界 | -| `Data/` | `14/14` 个类型声明已带 XML 注释 | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository`、`DataRepositoryOptions` | 看业务数据、统一设置文件、槽位存档与迁移契约 | -| `Setting/` | `12/12` 个类型声明已带 XML 注释 | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 看设置生命周期、应用语义、迁移接口和内置设置对象 | -| `Scene/` | `14/14` 个类型声明已带 XML 注释 | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 看场景行为、工厂 / root 边界和转场模型 | -| `UI/` | `19/19` 个类型声明已带 XML 注释 | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 看页面栈、层级 UI、输入动作和 UI 转场契约 | -| `Routing/` `Storage/` `Asset/` `Enums/` | `13/13` 个类型声明已带 XML 注释 | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与共享枚举 | +| 契约族 | 代表类型 | 建议先确认什么 | +| --- | --- | --- | +| `Config/` | `IConfigLoader`、`IConfigRegistry`、`IConfigTable`、`ConfigLoadException` | 配置表注册、只读访问和失败诊断边界 | +| `Data/` | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository`、`DataRepositoryOptions` | 业务数据、统一设置文件、槽位存档与迁移契约 | +| `Setting/` | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 设置生命周期、应用语义、迁移接口和内置设置对象 | +| `Scene/` | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 场景行为、工厂 / root 边界和转场模型 | +| `UI/` | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 页面栈、层级 UI、输入动作和 UI 转场契约 | +| `Routing/` `Storage/` `Asset/` `Enums/` | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry`、`UiLayer`、`SceneTransitionType` | 公共路由上下文、存储角色、资源注册表与共享枚举 | ## 最小接入路径 diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md index c5f6a36d..25a6fddb 100644 --- a/docs/zh-CN/api-reference/index.md +++ b/docs/zh-CN/api-reference/index.md @@ -18,7 +18,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题 ### 想确认“该装哪个包、先看哪类 API” -先读模块 README，再读对应 landing page： +先读模块 README，再读对应栏目入口页： - 入门入口：[`../getting-started/index.md`](../getting-started/index.md) - 根模块地图：仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md) @@ -51,7 +51,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题 ### 先看教程和专题页的情况 -- 你要的是最小接入路径，而不是逐个类型审计 +- 你要的是最小接入路径，而不是逐个类型展开阅读 - 你想确认模块组合方式、目录约定和推荐接线顺序 - 你在做从旧入口迁移到新入口的采用决策 diff --git a/docs/zh-CN/best-practices/architecture-patterns.md b/docs/zh-CN/best-practices/architecture-patterns.md index 726d1d6a..f452e972 100644 --- a/docs/zh-CN/best-practices/architecture-patterns.md +++ b/docs/zh-CN/best-practices/architecture-patterns.md @@ -1,3 +1,8 @@ +--- +title: 架构设计模式指南 +description: 围绕 GFramework 常见架构模式的职责划分、适用场景与组合建议。 +--- + # 架构设计模式指南 > 全面介绍 GFramework 中的架构设计模式，帮助你构建清晰、可维护、可扩展的游戏架构。 @@ -3440,4 +3445,4 @@ public void GetPlayerStatsQuery_ShouldReturnCorrectStats() **文档版本**: 2.0.0 **最后更新**: 2026-03-07 -**作者**: GFramework Team \ No newline at end of file +**作者**: GFramework Team diff --git a/docs/zh-CN/best-practices/error-handling.md b/docs/zh-CN/best-practices/error-handling.md index 2ec10bdf..2a9f354e 100644 --- a/docs/zh-CN/best-practices/error-handling.md +++ b/docs/zh-CN/best-practices/error-handling.md @@ -1,3 +1,8 @@ +--- +title: 错误处理最佳实践 +description: 总结 GFramework 项目中的错误建模、异常处理、日志记录与恢复策略。 +--- + # 错误处理最佳实践 > 本指南介绍 GFramework 中的错误处理模式和最佳实践，帮助你构建健壮、可维护的游戏应用。 diff --git a/docs/zh-CN/best-practices/index.md b/docs/zh-CN/best-practices/index.md index 3379dab3..ab8d236e 100644 --- a/docs/zh-CN/best-practices/index.md +++ b/docs/zh-CN/best-practices/index.md @@ -1,3 +1,8 @@ +--- +title: 最佳实践 +description: 汇总使用 GFramework 时的架构、性能、错误处理与多人游戏等实践建议。 +--- + # 最佳实践 本文档总结了使用 GFramework 的最佳实践和设计模式。 diff --git a/docs/zh-CN/best-practices/multiplayer.md b/docs/zh-CN/best-practices/multiplayer.md index 7366facc..8719db3a 100644 --- a/docs/zh-CN/best-practices/multiplayer.md +++ b/docs/zh-CN/best-practices/multiplayer.md @@ -1,3 +1,8 @@ +--- +title: 多人游戏架构指南 +description: 面向 GFramework 多人游戏项目的架构拆分、同步策略与网络优化建议。 +--- + # 多人游戏架构指南 > 基于 GFramework 架构设计高性能、可扩展的多人游戏系统。 @@ -544,3 +549,4 @@ public class ClientPresentationSystem : AbstractSystem ShowKillFeed(e.KillerId, e.PlayerId); } } +``` diff --git a/docs/zh-CN/best-practices/performance.md b/docs/zh-CN/best-practices/performance.md index 975e8d7f..70a03c64 100644 --- a/docs/zh-CN/best-practices/performance.md +++ b/docs/zh-CN/best-practices/performance.md @@ -1,3 +1,8 @@ +--- +title: 性能优化指南 +description: 整理 GFramework 项目在对象池、事件、协程与资源管理上的性能优化建议。 +--- + # 性能优化指南 > 全面的性能优化策略和最佳实践，帮助你构建高性能的游戏应用。 diff --git a/docs/zh-CN/contributing.md b/docs/zh-CN/contributing.md index 849c75ae..a9708858 100644 --- a/docs/zh-CN/contributing.md +++ b/docs/zh-CN/contributing.md @@ -1,3 +1,8 @@ +--- +title: 贡献指南 +description: 说明参与 GFramework 仓库贡献时的协作方式、提交流程与社区规范。 +--- + # 贡献指南 欢迎为 GFramework 贡献代码！本指南将帮助你了解如何参与项目开发。 diff --git a/docs/zh-CN/contributor/development-environment.md b/docs/zh-CN/contributor/development-environment.md index 69f77bc6..3f68a3fa 100644 --- a/docs/zh-CN/contributor/development-environment.md +++ b/docs/zh-CN/contributor/development-environment.md @@ -1,12 +1,17 @@ +--- +title: 开发环境能力清单 +description: 说明 GFramework 当前开发和 AI 协作依赖的环境能力、推荐工具与刷新方式。 +--- + # 开发环境能力清单 这份文档只记录对 `GFramework` 当前开发和 AI 协作真正有用的环境能力，不收录与本项目无关的系统工具。 如果某个工具没有出现在这里，默认表示它对当前仓库不是必需项，AI 也不应因为“系统里刚好装了”就优先使用它。 -## 当前环境基线 +## 当前验证环境 -当前仓库验证基线是： +当前仓库主要在下面这组环境中验证： - **运行环境**：WSL2 - **发行版**：Ubuntu 24.04 LTS @@ -114,4 +119,4 @@ LLM 索引文件与文档站一起部署在 GitHub Pages，遵循 `docs/.vitepre - 当前仓库构建、测试、文档或验证直接依赖它 - AI 在当前仓库中会高频使用，且能明显提升效率 - 新贡献者配置当前仓库开发环境时确实需要知道它 -- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。 \ No newline at end of file +- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。 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..a113752f 100644 --- a/docs/zh-CN/core/context.md +++ b/docs/zh-CN/core/context.md @@ -1,4 +1,9 @@ -# Context +--- +title: 上下文（Context） +description: 说明 IArchitectureContext 与 ArchitectureContext 的统一上下文入口和当前推荐用法。 +--- + +# 上下文（Context） `IArchitectureContext` 是框架的统一上下文入口。 diff --git a/docs/zh-CN/core/cqrs.md b/docs/zh-CN/core/cqrs.md index 3431e1d9..33b8fb68 100644 --- a/docs/zh-CN/core/cqrs.md +++ b/docs/zh-CN/core/cqrs.md @@ -1,6 +1,6 @@ --- title: CQRS -description: Cqrs 模块族的运行时、契约层、生成器入口，以及 XML / API 阅读链路。 +description: Cqrs 模块族的运行时、契约层、生成器入口，以及源码与 API 阅读链路。 --- # CQRS @@ -169,17 +169,17 @@ RegisterCqrsPipelineBehavior>(); - 在维护历史代码：允许继续使用旧 Command / Query - 在写新功能或新模块：优先使用 CQRS -## XML 覆盖基线 +## 源码阅读入口 -下面这份 inventory 记录的是 `2026-04-22` 对 `Cqrs` 家族做的一轮轻量 XML 盘点结果：只统计当前运行时、契约层和生成器入口中的类型声明级 XML 覆盖，用来校对 README、landing page 与 API 入口，不把它表述成成员级契约全审计。 +如果你需要直接回到源码确认 CQRS 契约，建议按下面这几组入口阅读： -| 类型族 | 基线状态 | 代表类型 | 阅读重点 | -| --- | --- | --- | --- | -| `GFramework.Cqrs.Abstractions/Cqrs/` | `20/20` 个类型声明已带 XML 注释 | `ICqrsRuntime`、`ICqrsHandlerRegistrar`、`IPipelineBehavior<,>`、`IRequestHandler<,>`、`Unit` | 先看请求、处理器和 runtime seam 的最小契约 | -| `GFramework.Cqrs/Command` `Query` `Notification` `Request` `Extensions` | `7/7` 个类型声明已带 XML 注释 | `CommandBase`、`QueryBase`、`NotificationBase`、`ContextAwareCqrsExtensions` | 看业务侧常用基类和上下文发送入口 | -| `GFramework.Cqrs/Cqrs/` | `12/12` 个类型声明已带 XML 注释 | `AbstractCommandHandler<,>`、`AbstractQueryHandler<,>`、`AbstractNotificationHandler<>`、`LoggingBehavior<,>` | 看默认处理器基类、上下文注入与行为管道 | -| `GFramework.Cqrs` 根入口与 `Internal/` | `19/19` 个类型声明已带 XML 注释 | `CqrsRuntimeFactory`、`ICqrsHandlerRegistry`、`CqrsHandlerRegistryAttribute`、`CqrsReflectionFallbackAttribute`、`DefaultCqrsRegistrationService` | 看 runtime 创建入口、registry 协议、fallback 语义和程序集去重规则 | -| `GFramework.Cqrs.SourceGenerators/Cqrs/` | `3/3` 个类型声明已带 XML 注释 | `CqrsHandlerRegistryGenerator`、`RuntimeTypeReferenceSpec`、`OrderedRegistrationKind` | 看生成注册器、精确 type lookup 和 fallback 诊断边界 | +| 类型族 | 代表类型 | 建议先确认什么 | +| --- | --- | --- | +| `GFramework.Cqrs.Abstractions/Cqrs/` | `ICqrsRuntime`、`ICqrsHandlerRegistrar`、`IPipelineBehavior<,>`、`IRequestHandler<,>`、`Unit` | 请求、处理器和 runtime seam 的最小契约 | +| `GFramework.Cqrs/Command` `Query` `Notification` `Request` `Extensions` | `CommandBase`、`QueryBase`、`NotificationBase`、`ContextAwareCqrsExtensions` | 业务侧常用基类和上下文发送入口 | +| `GFramework.Cqrs/Cqrs/` | `AbstractCommandHandler<,>`、`AbstractQueryHandler<,>`、`AbstractNotificationHandler<>`、`LoggingBehavior<,>` | 默认处理器基类、上下文注入与行为管道 | +| `GFramework.Cqrs` 根入口与 `Internal/` | `CqrsRuntimeFactory`、`ICqrsHandlerRegistry`、`CqrsHandlerRegistryAttribute`、`CqrsReflectionFallbackAttribute`、`DefaultCqrsRegistrationService` | runtime 创建入口、registry 协议、fallback 语义和程序集去重规则 | +| `GFramework.Cqrs.SourceGenerators/Cqrs/` | `CqrsHandlerRegistryGenerator`、`RuntimeTypeReferenceSpec`、`OrderedRegistrationKind` | 生成注册器、精确 type lookup 和 fallback 诊断边界 | ## 继续阅读 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/index.md b/docs/zh-CN/core/index.md index 39435bf5..c5e708e4 100644 --- a/docs/zh-CN/core/index.md +++ b/docs/zh-CN/core/index.md @@ -1,6 +1,6 @@ --- title: Core -description: GFramework.Core 与 GFramework.Core.Abstractions 的运行时入口、采用顺序和 XML 阅读导航。 +description: GFramework.Core 与 GFramework.Core.Abstractions 的运行时入口、采用顺序和源码阅读导航。 --- # Core @@ -82,22 +82,21 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions 统一入口见 [`../api-reference/index.md`](../api-reference/index.md)。 -## XML 覆盖基线 +## 源码阅读入口 -下面这份 inventory 记录的是 `2026-04-22` 对 `GFramework.Core` 做的一轮轻量 XML 盘点结果：只统计顶层目录中的公开 / -内部类型声明是否带 XML 注释，用来确认阅读入口和治理优先级；成员级 ````、````、异常语义与线程说明仍需要继续细审。 +如果你准备直接回到源码和 XML 文档确认契约，建议按能力域分批阅读，而不是按文件数量排查： -| 类型族 | 基线状态 | 代表类型 | 阅读重点 | -| --- | --- | --- | --- | -| `Architectures/` | `16/16` 个类型声明已带 XML 注释 | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ArchitecturePhaseCoordinator` | 看架构启动、模块安装、阶段切换和上下文暴露边界 | -| `Services/` | `6/6` 个类型声明已带 XML 注释 | `ServiceModuleManager`、`CommandExecutorModule`、`CqrsRuntimeModule` | 看服务模块的注册顺序、销毁语义和默认接线 | -| `Command/` `Query/` | `15/15` 个类型声明已带 XML 注释 | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand`、`AbstractQuery` | 看旧入口兼容面与向 `CQRS` 迁移时还保留了哪些执行契约 | -| `Events/` `Property/` | `19/19` 个类型声明已带 XML 注释 | `EventBus`、`EnhancedEventBus`、`BindableProperty`、`OrEvent` | 看事件传播、解绑约束和可绑定属性的订阅语义 | -| `State/` `StateManagement/` | `10/10` 个类型声明已带 XML 注释 | `StateMachine`、`StateMachineSystem`、`Store`、`StoreBuilder` | 看状态切换、selector / middleware / dispatch 的单向流边界 | -| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `43/43` 个类型声明已带 XML 注释 | `CoroutineScheduler`、`CoroutineHandle`、`WaitForSecondsRealtime`、`PauseStackManager`、`AsyncKeyLockManager` | 看调度阶段、等待指令、时间源和暂停 / 锁的线程语义 | -| `Resource/` `Pool/` | `8/8` 个类型声明已带 XML 注释 | `ResourceManager`、`AutoReleaseStrategy`、`ManualReleaseStrategy`、`AbstractObjectPoolSystem` | 看资源句柄释放策略与对象池复用约束 | -| `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `31/31` 个类型声明已带 XML 注释 | `ConsoleLogger`、`CompositeLogger`、`LocalizationManager`、`ConfigurationManager`、`MicrosoftDiContainer` | 看日志组装、格式化 / filter、配置监听、环境对象与容器适配 | -| `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `34/34` 个类型声明已带 XML 注释 | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result` | 看默认基类、上下文感知 helper、数值格式化和通用扩展的使用边界 | +| 类型族 | 代表类型 | 建议先确认什么 | +| --- | --- | --- | +| `Architectures/` | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ArchitecturePhaseCoordinator` | 架构启动、模块安装、阶段切换和上下文暴露边界 | +| `Services/` | `ServiceModuleManager`、`CommandExecutorModule`、`CqrsRuntimeModule` | 服务模块的注册顺序、销毁语义和默认接线 | +| `Command/` `Query/` | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand`、`AbstractQuery` | 旧入口兼容面，以及向 `CQRS` 迁移时保留的执行契约 | +| `Events/` `Property/` | `EventBus`、`EnhancedEventBus`、`BindableProperty`、`OrEvent` | 事件传播、解绑约束和可绑定属性的订阅语义 | +| `State/` `StateManagement/` | `StateMachine`、`StateMachineSystem`、`Store`、`StoreBuilder` | 状态切换，以及 selector / middleware / dispatch 的单向流边界 | +| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `CoroutineScheduler`、`CoroutineHandle`、`WaitForSecondsRealtime`、`PauseStackManager`、`AsyncKeyLockManager` | 调度阶段、等待指令、时间源，以及暂停 / 锁的线程语义 | +| `Resource/` `Pool/` | `ResourceManager`、`AutoReleaseStrategy`、`ManualReleaseStrategy`、`AbstractObjectPoolSystem` | 资源句柄释放策略与对象池复用约束 | +| `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `ConsoleLogger`、`CompositeLogger`、`LocalizationManager`、`ConfigurationManager`、`MicrosoftDiContainer` | 日志组装、格式化 / filter、配置监听、环境对象与容器适配 | +| `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result` | 默认基类、上下文感知 helper、数值格式化和通用扩展的使用边界 | ## 最小接入路径 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 包使用说明 ## 概述 diff --git a/docs/zh-CN/ecs/arch.md b/docs/zh-CN/ecs/arch.md index 46c1789b..44ac1bf0 100644 --- a/docs/zh-CN/ecs/arch.md +++ b/docs/zh-CN/ecs/arch.md @@ -1,6 +1,6 @@ --- title: Arch ECS 集成 -description: GFramework.Ecs.Arch 的默认运行时装配路径、系统桥接方式与 XML 阅读入口。 +description: GFramework.Ecs.Arch 的默认运行时装配路径、系统桥接方式与源码阅读入口。 --- # Arch ECS 集成 @@ -127,14 +127,14 @@ ecsModule.Update(deltaTime); - `Priority` 影响 `ArchEcsModule` 作为服务模块的排序 - `EnableStatistics` 目前保留在公开配置面上；采用时应以源码 XML 注释和实现行为为准，而不是依赖旧文档推断 -## 类型族级 XML Inventory +## 源码阅读入口 -| 类型族 | 代表类型 | XML 状态 | 阅读重点 | -| --- | --- | --- | --- | -| 装配入口 | `ArchExtensions` | 已覆盖 | `UseArch(...)` 的时机、链式调用返回值 | -| 服务模块 | `ArchEcsModule` | 已覆盖 | `World` 注册、系统收集、模块销毁顺序 | -| 系统桥接层 | `ArchSystemAdapter` | 已覆盖 | `OnArchInitialize` / `OnUpdate` / `OnArchDispose` | -| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 已覆盖 | 组件布局、查询写法、最小集成样例 | +| 类型族 | 代表类型 | 建议先确认什么 | +| --- | --- | --- | +| 装配入口 | `ArchExtensions` | `UseArch(...)` 的时机、链式调用返回值 | +| 服务模块 | `ArchEcsModule` | `World` 注册、系统收集、模块销毁顺序 | +| 系统桥接层 | `ArchSystemAdapter` | `OnArchInitialize` / `OnUpdate` / `OnArchDispose` | +| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 组件布局、查询写法和最小集成样例 | ## 相关入口 diff --git a/docs/zh-CN/ecs/index.md b/docs/zh-CN/ecs/index.md index b2b7e332..255226bc 100644 --- a/docs/zh-CN/ecs/index.md +++ b/docs/zh-CN/ecs/index.md @@ -1,6 +1,6 @@ --- title: ECS 系统集成 -description: GFramework 当前 ECS 模块族的包边界、采用顺序与 XML 阅读入口。 +description: GFramework 当前 ECS 模块族的包边界、采用顺序与源码阅读入口。 --- # ECS 系统集成 @@ -118,16 +118,16 @@ public sealed class GameLoop 3. 只想保留共享边界时继续读 [`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md) 4. 统一查阅 README / docs / XML 入口时回到 [`../api-reference/index.md`](../api-reference/index.md) -## 类型族级 XML Inventory +## 源码阅读入口 -下表记录当前 `Ecs.Arch` family 的类型声明级 XML 基线，便于从 README、站内 landing 和源码之间建立一致的审计入口。 +如果你要从栏目入口页回到源码和 XML 文档，建议按下面的入口阅读： -| 包 | 类型族 | 代表类型 | XML 状态 | 阅读重点 | -| --- | --- | --- | --- | --- | -| `GFramework.Ecs.Arch` | 运行时装配与模块生命周期 | `ArchExtensions`、`ArchEcsModule` | 已覆盖 | `UseArch(...)` 的接入时机、`World` 注册、模块优先级 | -| `GFramework.Ecs.Arch` | 系统桥接层 | `ArchSystemAdapter` | 已覆盖 | GFramework `ISystem` 生命周期如何桥接到 Arch `ISystem` | -| `GFramework.Ecs.Arch` | 示例组件与系统 | `Position`、`Velocity`、`MovementSystem` | 已覆盖 | 查询写法、组件布局、最小可运行示例 | -| `GFramework.Ecs.Arch.Abstractions` | 契约与配置对象 | `IArchEcsModule`、`IArchSystemAdapter`、`ArchOptions` | 已覆盖 | 共享宿主循环、测试替身、跨程序集配置边界 | +| 包 | 类型族 | 代表类型 | 建议先确认什么 | +| --- | --- | --- | --- | +| `GFramework.Ecs.Arch` | 运行时装配与模块生命周期 | `ArchExtensions`、`ArchEcsModule` | `UseArch(...)` 的接入时机、`World` 注册、模块优先级 | +| `GFramework.Ecs.Arch` | 系统桥接层 | `ArchSystemAdapter` | GFramework `ISystem` 生命周期如何桥接到 Arch `ISystem` | +| `GFramework.Ecs.Arch` | 示例组件与系统 | `Position`、`Velocity`、`MovementSystem` | 查询写法、组件布局和最小可运行示例 | +| `GFramework.Ecs.Arch.Abstractions` | 契约与配置对象 | `IArchEcsModule`、`IArchSystemAdapter`、`ArchOptions` | 共享宿主循环、测试替身和跨程序集配置边界 | ## 边界说明 diff --git a/docs/zh-CN/faq.md b/docs/zh-CN/faq.md index 0401105e..3f531d95 100644 --- a/docs/zh-CN/faq.md +++ b/docs/zh-CN/faq.md @@ -1,3 +1,8 @@ +--- +title: 常见问题（FAQ） +description: 汇总 GFramework 在安装、架构、命令、事件与性能方面的常见问题。 +--- + # 常见问题（FAQ） ## 安装与配置 diff --git a/docs/zh-CN/game/config-system.md b/docs/zh-CN/game/config-system.md index 14a6e727..5e454085 100644 --- a/docs/zh-CN/game/config-system.md +++ b/docs/zh-CN/game/config-system.md @@ -1,3 +1,8 @@ +--- +title: 游戏内容配置系统 +description: 说明 GFramework.Game 配置系统的定位、目录约定、生成能力与最小采用路径。 +--- + # 游戏内容配置系统 > 面向静态游戏内容的 AI-First 配表方案 diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index 7efe4be0..a30a4b02 100644 --- a/docs/zh-CN/game/index.md +++ b/docs/zh-CN/game/index.md @@ -1,6 +1,6 @@ --- title: Game -description: GFramework.Game family 的运行时入口、采用顺序与 XML 阅读基线。 +description: GFramework.Game family 的运行时入口、采用顺序与源码阅读导航。 --- # Game @@ -103,15 +103,15 @@ IStorage storage = new FileStorage("GameData", serializer); 4. [setting](./setting.md) 5. [scene](./scene.md) 或 [ui](./ui.md) -## Game Family XML 覆盖基线 +## 源码与 API 阅读入口 -下面这份 inventory 记录的是 `2026-04-23` 对 `Game` family 做的一轮轻量 XML 盘点结果：只统计公开 / 内部类型声明是否带 XML 注释，用来建立 README / landing / API 阅读链路；成员级 `param`、`returns`、`exception` 与生命周期说明仍需要后续波次继续细化。 +如果你已经完成栏目入口页阅读，下一步通常不是看统计表，而是按模块角色回到源码和 XML 文档： -| 模块 | 基线状态 | 代表类型 | 阅读重点 | -| --- | --- | --- | --- | -| `GFramework.Game` | `56/56` 个类型声明已带 XML 注释 | `YamlConfigLoader`、`SettingsModel`、`SceneRouterBase`、`UiRouterBase` | 先看运行时默认实现、配置加载、设置编排和路由基类 | -| `GFramework.Game.Abstractions` | `80/80` 个类型声明已带 XML 注释 | `IConfigRegistry`、`ISaveRepository`、`ISettingsSystem`、`ISceneRouter`、`IUiRouter` | 再看契约层边界，决定项目哪些程序集只依赖接口 | -| `GFramework.Game.SourceGenerators` | `2/2` 个类型声明已带 XML 注释 | `SchemaConfigGenerator`、`ConfigSchemaDiagnostics` | 最后看 schema 生成入口与诊断模型，确认配置系统的编译期链路 | +| 模块 | 代表类型 | 建议先确认什么 | +| --- | --- | --- | +| `GFramework.Game` | `YamlConfigLoader`、`SettingsModel`、`SceneRouterBase`、`UiRouterBase` | 默认运行时实现、配置加载、设置编排和路由基类 | +| `GFramework.Game.Abstractions` | `IConfigRegistry`、`ISaveRepository`、`ISettingsSystem`、`ISceneRouter`、`IUiRouter` | 契约层边界，以及项目中哪些程序集只应依赖接口 | +| `GFramework.Game.SourceGenerators` | `SchemaConfigGenerator`、`ConfigSchemaDiagnostics` | schema 生成入口与诊断模型，确认配置系统的编译期链路 | ## 与真实接法的关系 diff --git a/docs/zh-CN/getting-started/index.md b/docs/zh-CN/getting-started/index.md index 50f15211..94d528e9 100644 --- a/docs/zh-CN/getting-started/index.md +++ b/docs/zh-CN/getting-started/index.md @@ -1,3 +1,8 @@ +--- +title: 入门指南 +description: 概览 GFramework 的模块组成、最小接入路径与继续阅读入口。 +--- + # 入门指南 这一部分只回答三个问题： diff --git a/docs/zh-CN/getting-started/installation.md b/docs/zh-CN/getting-started/installation.md index 403bf708..d1864548 100644 --- a/docs/zh-CN/getting-started/installation.md +++ b/docs/zh-CN/getting-started/installation.md @@ -1,3 +1,8 @@ +--- +title: 安装配置 +description: 说明 GFramework 各运行时与 source generator 包的安装选择和配置方式。 +--- + # 安装配置 GFramework 提供多种安装方式，您可以根据项目需求选择合适的包进行安装。 diff --git a/docs/zh-CN/getting-started/quick-start.md b/docs/zh-CN/getting-started/quick-start.md index 6667e799..6d37ea89 100644 --- a/docs/zh-CN/getting-started/quick-start.md +++ b/docs/zh-CN/getting-started/quick-start.md @@ -1,3 +1,8 @@ +--- +title: 快速开始 +description: 通过只依赖 Core 的最小示例快速跑通 GFramework 基础架构。 +--- + # 快速开始 本页给出一个只依赖 `Core` 的最小路径，用来确认你已经成功接入 `Architecture`、`Model`、`System` 与旧版命令执行器。 diff --git a/docs/zh-CN/godot/coroutine.md b/docs/zh-CN/godot/coroutine.md index ce861f17..1d4e6bfe 100644 --- a/docs/zh-CN/godot/coroutine.md +++ b/docs/zh-CN/godot/coroutine.md @@ -1,3 +1,8 @@ +--- +title: Godot 协程系统 +description: 说明 GFramework.Godot.Coroutine 的宿主集成能力、阶段语义与使用方式。 +--- + # Godot 协程系统 ## 概述 diff --git a/docs/zh-CN/source-generators/auto-register-module-generator.md b/docs/zh-CN/source-generators/auto-register-module-generator.md index d216f4e4..57d32943 100644 --- a/docs/zh-CN/source-generators/auto-register-module-generator.md +++ b/docs/zh-CN/source-generators/auto-register-module-generator.md @@ -1,3 +1,8 @@ +--- +title: AutoRegisterModule 生成器 +description: 介绍 AutoRegisterModule 生成器如何为模块安装生成固定顺序的注册代码。 +--- + # AutoRegisterModule 生成器 > 为架构模块生成固定顺序的组件注册代码，收敛 `Install(IArchitecture)` 样板。 @@ -149,5 +154,5 @@ partial class GameplayModule ## 相关文档 -- [源码生成器总览](./index) -- [Context Get 注入生成器](./context-get-generator) +- [源码生成器总览](./index.md) +- [Context Get 注入生成器](./context-get-generator.md) diff --git a/docs/zh-CN/source-generators/auto-scene-generator.md b/docs/zh-CN/source-generators/auto-scene-generator.md index 92927daa..311daf20 100644 --- a/docs/zh-CN/source-generators/auto-scene-generator.md +++ b/docs/zh-CN/source-generators/auto-scene-generator.md @@ -1,3 +1,8 @@ +--- +title: AutoScene 生成器 +description: 介绍 AutoScene 生成器如何生成场景包装入口与统一场景键声明。 +--- + # AutoScene 生成器 > 为场景根节点生成 `GetScene()` 样板，统一场景键声明与行为包装。 @@ -116,5 +121,5 @@ partial class GameplayRoot ## 相关文档 -- [源码生成器总览](./index) -- [AutoUiPage 生成器](./auto-ui-page-generator) +- [源码生成器总览](./index.md) +- [AutoUiPage 生成器](./auto-ui-page-generator.md) diff --git a/docs/zh-CN/source-generators/auto-ui-page-generator.md b/docs/zh-CN/source-generators/auto-ui-page-generator.md index 3b1f6a41..50a88eb3 100644 --- a/docs/zh-CN/source-generators/auto-ui-page-generator.md +++ b/docs/zh-CN/source-generators/auto-ui-page-generator.md @@ -1,3 +1,8 @@ +--- +title: AutoUiPage 生成器 +description: 介绍 AutoUiPage 生成器如何为 Godot UI 页面生成页面包装入口。 +--- + # AutoUiPage 生成器 > 为 Godot UI 页面生成 `GetPage()` 样板，统一页面键与层级声明。 @@ -149,6 +154,6 @@ public partial class PauseMenu : Control ## 相关文档 -- [源码生成器总览](./index) -- [GetNode 生成器](./get-node-generator) -- [BindNodeSignal 生成器](./bind-node-signal-generator) +- [源码生成器总览](./index.md) +- [GetNode 生成器](./get-node-generator.md) +- [BindNodeSignal 生成器](./bind-node-signal-generator.md) diff --git a/docs/zh-CN/source-generators/bind-node-signal-generator.md b/docs/zh-CN/source-generators/bind-node-signal-generator.md index b64ad0aa..b357c7a9 100644 --- a/docs/zh-CN/source-generators/bind-node-signal-generator.md +++ b/docs/zh-CN/source-generators/bind-node-signal-generator.md @@ -11,7 +11,7 @@ description: 说明 [BindNodeSignal] 当前生成什么、如何与 GetNode 协 - 特性来源：`GFramework.Godot.SourceGenerators.Abstractions` - 生成器实现：`GFramework.Godot.SourceGenerators` -- 目标字段基线：`nodeFieldName` 指向的字段必须继承 `Godot.Node` +- 使用前提：`nodeFieldName` 指向的字段必须继承 `Godot.Node` ## 最小用法 diff --git a/docs/zh-CN/source-generators/context-get-generator.md b/docs/zh-CN/source-generators/context-get-generator.md index 7d9f2b0b..71019990 100644 --- a/docs/zh-CN/source-generators/context-get-generator.md +++ b/docs/zh-CN/source-generators/context-get-generator.md @@ -1,3 +1,8 @@ +--- +title: Context Get 注入生成器 +description: 介绍 Context Get 注入生成器的能力、依赖前提与使用方式。 +--- + # Context Get 注入生成器 > 自动注入架构组件，消除样板代码 diff --git a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md index c30d3869..82ddaf42 100644 --- a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md +++ b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md @@ -116,7 +116,7 @@ RegisterCqrsHandlersFromAssemblies( 这条诊断的含义不是“某个 handler 写错了”，而是“当前 runtime 合同不足以安全承载这轮生成结果”。 -## XML / API 阅读入口 +## 源码与 API 阅读入口 如果你要核对生成器对外暴露的契约，优先看这些类型： diff --git a/docs/zh-CN/source-generators/enum-generator.md b/docs/zh-CN/source-generators/enum-generator.md index 46450112..347329fb 100644 --- a/docs/zh-CN/source-generators/enum-generator.md +++ b/docs/zh-CN/source-generators/enum-generator.md @@ -1,3 +1,8 @@ +--- +title: 枚举扩展生成器 +description: 介绍枚举扩展生成器生成的 IsX 与 IsIn 方法及其典型用法。 +--- + # 枚举扩展生成器 > 自动为枚举类型生成扩展方法 @@ -267,6 +272,6 @@ public class PlayerController ## 相关文档 -- [Source Generators 概述](./index) -- [日志生成器](./logging-generator) -- [ContextAware 生成器](./context-aware-generator) +- [Source Generators 概述](./index.md) +- [日志生成器](./logging-generator.md) +- [ContextAware 生成器](./context-aware-generator.md) diff --git a/docs/zh-CN/source-generators/get-node-generator.md b/docs/zh-CN/source-generators/get-node-generator.md index f8843f63..2a5b39f3 100644 --- a/docs/zh-CN/source-generators/get-node-generator.md +++ b/docs/zh-CN/source-generators/get-node-generator.md @@ -11,7 +11,7 @@ description: 说明 [GetNode] 当前生成什么、路径如何推断，以及 _ - 特性来源：`GFramework.Godot.SourceGenerators.Abstractions` - 生成器实现：`GFramework.Godot.SourceGenerators` -- 目标类型基线：字段类型必须继承 `Godot.Node` +- 使用前提：字段类型必须继承 `Godot.Node` ## 最小用法 diff --git a/docs/zh-CN/source-generators/logging-generator.md b/docs/zh-CN/source-generators/logging-generator.md index 4e8c1425..0aad18e8 100644 --- a/docs/zh-CN/source-generators/logging-generator.md +++ b/docs/zh-CN/source-generators/logging-generator.md @@ -1,3 +1,8 @@ +--- +title: 日志生成器 +description: 介绍日志生成器如何为标记类型生成 ILogger 字段并减少日志样板。 +--- + # 日志生成器 > GFramework.Core.SourceGenerators 自动生成日志代码，减少样板代码 @@ -336,6 +341,6 @@ public static partial class StaticHelper **相关文档**： -- [Source Generators 概述](./index) -- [枚举扩展生成器](./enum-generator) -- [ContextAware 生成器](./context-aware-generator) +- [Source Generators 概述](./index.md) +- [枚举扩展生成器](./enum-generator.md) +- [ContextAware 生成器](./context-aware-generator.md) diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 699856ff..68d1187f 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -1,3 +1,8 @@ +--- +title: 故障排除与调试 +description: 提供 GFramework 常见安装、架构、事件与运行时问题的排查思路。 +--- + # 故障排除与调试 本指南帮助你诊断和解决 GFramework 使用中的常见问题。 @@ -2047,12 +2052,12 @@ public class MyLoader : IResourceLoader 如果问题仍未解决： -1. 查看 [Core 文档](/zh-CN/core/) 了解更多细节 -2. 查看 [架构组件](/zh-CN/core/architecture) 了解架构设计 -3. 查看 [Godot 集成](/zh-CN/godot/) 了解 Godot 特定问题 +1. 查看 [Core 文档](/zh-CN/core/index.md) 了解更多细节 +2. 查看 [架构组件](/zh-CN/core/architecture.md) 了解架构设计 +3. 查看 [Godot 集成](/zh-CN/godot/index.md) 了解 Godot 特定问题 4. 在 [GitHub Issues](https://github.com/GeWuYou/GFramework/issues) 提交问题 -5. 查看 [教程](/zh-CN/tutorials/) 中的示例代码 -6. 查看 [常见问题](/zh-CN/faq) 获取快速答案 +5. 查看 [教程](/zh-CN/tutorials/index.md) 中的示例代码 +6. 查看 [常见问题](/zh-CN/faq.md) 获取快速答案 --- diff --git a/docs/zh-CN/tutorials/advanced-patterns.md b/docs/zh-CN/tutorials/advanced-patterns.md index 516f1b95..d06e5aeb 100644 --- a/docs/zh-CN/tutorials/advanced-patterns.md +++ b/docs/zh-CN/tutorials/advanced-patterns.md @@ -1,3 +1,8 @@ +--- +title: 高级模式教程 +description: 通过高级模式示例说明 GFramework 中的复杂架构组织与扩展方式。 +--- + # 高级模式教程 > 深入学习 GFramework 的高级特性和设计模式，构建更复杂和可维护的游戏系统。 @@ -1637,4 +1642,4 @@ public partial class NetworkController : Node, IController --- **教程版本**: 1.0.0 -**更新日期**: 2026-01-12 \ No newline at end of file +**更新日期**: 2026-01-12 diff --git a/docs/zh-CN/tutorials/basic/index.md b/docs/zh-CN/tutorials/basic/index.md index 5afb00dc..00a34f20 100644 --- a/docs/zh-CN/tutorials/basic/index.md +++ b/docs/zh-CN/tutorials/basic/index.md @@ -1,3 +1,8 @@ +--- +title: 基础教程：从零开始使用 GFramework +description: 从零开始串联环境准备、项目搭建与核心概念的基础教程入口。 +--- + # 基础教程：从零开始使用 GFramework 欢迎来到 GFramework 的基础教程！本教程将带你从零开始，创建一个完整的计数器应用，逐步掌握 GFramework 的核心概念和最佳实践。 diff --git a/docs/zh-CN/tutorials/index.md b/docs/zh-CN/tutorials/index.md index 35c12691..205d881d 100644 --- a/docs/zh-CN/tutorials/index.md +++ b/docs/zh-CN/tutorials/index.md @@ -1,3 +1,8 @@ +--- +title: 教程 +description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习阶段选择阅读路径。 +--- + # 教程 欢迎来到 GFramework 教程中心！这里提供从入门到精进的完整学习路径，帮助你掌握这个面向游戏开发的模块化 C# 框架。