From bf37104c6894fb3a1d5c81efbf22a8266d3a7ce1 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Fri, 24 Apr 2026 13:00:09 +0800 Subject: [PATCH 1/4] =?UTF-8?q?docs(zh-cn):=20=E8=A1=A5=E9=BD=90=E9=A6=96?= =?UTF-8?q?=E9=A1=B5=E4=B8=8E=E5=9F=BA=E7=A1=80=E6=95=99=E7=A8=8B=E5=85=83?= =?UTF-8?q?=E6=95=B0=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 补充 zh-CN 首页与基础教程章节页的 frontmatter title 与 description - 更新文档治理 topic 的恢复点、批次指标与下一步 --- ...ation-full-coverage-governance-tracking.md | 17 ++++++--- ...entation-full-coverage-governance-trace.md | 38 +++++++++---------- docs/zh-CN/index.md | 3 +- docs/zh-CN/tutorials/basic/01-environment.md | 2 + .../zh-CN/tutorials/basic/02-project-setup.md | 2 + .../zh-CN/tutorials/basic/03-counter-basic.md | 2 + .../tutorials/basic/04-model-refactor.md | 2 + .../tutorials/basic/05-command-system.md | 2 + .../tutorials/basic/06-utility-system.md | 2 + docs/zh-CN/tutorials/basic/07-summary.md | 2 + 10 files changed, 44 insertions(+), 28 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 1339356a..7ddf9f2f 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,12 +12,12 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-026` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-027` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 收口 PR `#282` 的 latest-head review follow-up，保持 active tracking / trace 只承载当前恢复入口 + - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，本批已收口 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 的 metadata 缺口 - 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明 - - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险 metadata 缺口、坏链与 Markdown 结构问题 + - 继续优先处理低风险 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/` @@ -25,12 +25,14 @@ ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 +- `2026-04-24` 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 batch baseline 时，当前分支累计 diff 为 `0` 个文件；本批 write set 聚焦 `8` 个文档页面与 `2` 个 `ai-plan` 入口文件，预计提交后分支 diff 为 `10 / 75` 个 changed files。 - `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` 链接写法 +- 本批次补齐了 `docs/zh-CN/index.md` 的 `description`，以及 `docs/zh-CN/tutorials/basic/01-07.md` 的 `title` / `description`，让首页和基础教程章节页拥有完整 frontmatter metadata。 - `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`、 @@ -68,12 +70,15 @@ - 结果：当前无命中；`/zh-CN/core/architecture` 与 `/zh-CN/faq` 已统一补成显式 `.md` 链接。 - `2026-04-24` `bun run build`（工作目录：`docs/`） - 结果：通过；文档标题本地化、站内链接修正与 `ai-plan` 归档瘦身落地后站点仍可正常构建，仅保留既有大 chunk warning。 +- `2026-04-24` `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` frontmatter 是否缺 `title` / `description`） + - 结果：通过；当前带 frontmatter 的 `docs/zh-CN` 页面已无 `title` / `description` 缺口。 +- `2026-04-24` `bun run build`（工作目录：`docs/`） + - 结果：通过；首页与基础教程 metadata 补齐后站点仍可正常构建，仅保留既有大 chunk warning。 ## 下一步 -1. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8` - 个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。 -2. 推送当前 follow-up commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。 +1. 推送本批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。 +2. 若继续执行 `$gframework-batch-boot 75`，优先盘点 `docs/zh-CN` 中仍缺完整 frontmatter 的页面，并按模块或教程小批次补齐 metadata。 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`、 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 5336d9f7..d0ad6fb2 100644 --- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -2,32 +2,28 @@ ## 2026-04-24 -### 当前恢复点：RP-026 +### 当前恢复点：RP-027 -- 使用 `$gframework-pr-review` 抓取 PR `#282`，确认 latest head commit - `982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread。 -- 按“只处理 latest-head unresolved threads 中仍成立的问题”的原则，本轮仅收口 4 条本地可复现的 follow-up： - - 将 `tracking.md` 与 `trace.md` 的活动入口瘦身，并把 `RP-023` 到 `RP-025` 的细节迁入新 archive 文件 - - 将 `docs/zh-CN/core/context.md` 的标题与主标题本地化为 `上下文（Context）` - - 将 `docs/zh-CN/troubleshooting.md` 中 `/zh-CN/core/architecture` 与 `/zh-CN/faq` 统一补成显式 `.md` 链接 +- 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 `$gframework-batch-boot 75` baseline，确认批次开始时当前分支累计 diff 为 `0` 个文件。 +- 选择“frontmatter metadata 缺口”作为本批次低风险切片，不继续扩大到正文语义改写或跨模块文档重写。 +- 本批次补齐了 `docs/zh-CN/index.md` 的 `description`，以及 `docs/zh-CN/tutorials/basic/01-07.md` 的 `title` / `description`。 -### 当前决策（RP-026） +### 当前决策（RP-027） -- PR review follow-up 继续遵守“先本地验证，再决定是否修复”；对已经过时或无法在当前分支复现的评论不做追随式修改。 -- active `ai-plan` 入口只保留当前恢复点、活动事实、风险、最新验证与下一步；批次细节统一迁入 `archive/`。 -- `docs/zh-CN` 页面应优先使用中文标题；同一帮助块中的绝对站内链接应保持一致的显式 `.md` 写法。 +- 当 branch diff 明显低于 `75` 文件阈值时，优先消化低风险 metadata / 链接 / Markdown 结构缺口，避免在同一批次混入高语义成本的文案重写。 +- active `ai-plan` 入口继续保持轻量，只记录当前恢复点、batch metric、验证结果与下一批候选项。 +- 当前 WSL 会话继续使用显式 `--git-dir` / `--work-tree` 绑定执行 Git，避免 `git.exe` 失效带来的路径问题。 -### 当前验证（RP-026） +### 当前验证（RP-027） -- PR review 抓取： - - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#282` 处于 `OPEN`，最新 review 线程与测试状态已成功解析，测试汇总为 `2156 passed`。 -- 链接巡检： - - `rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(? Date: Fri, 24 Apr 2026 13:10:41 +0800 Subject: [PATCH 2/4] =?UTF-8?q?docs(zh-cn):=20=E7=BB=9F=E4=B8=80=E7=AB=99?= =?UTF-8?q?=E5=86=85=E9=93=BE=E6=8E=A5=E6=98=BE=E5=BC=8F=E6=89=A9=E5=B1=95?= =?UTF-8?q?=E5=90=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新教程、最佳实践、Core 与 Godot 页面中的站内 Markdown 链接写法 - 补充文档治理 topic 的恢复点、验证结果与分支阈值指标 --- ...ation-full-coverage-governance-tracking.md | 17 +++++++---- ...entation-full-coverage-governance-trace.md | 30 +++++++++---------- .../best-practices/architecture-patterns.md | 12 ++++---- .../best-practices/mobile-optimization.md | 8 ++--- docs/zh-CN/core/resource.md | 8 ++--- docs/zh-CN/core/state-machine.md | 8 ++--- docs/zh-CN/godot/pause.md | 8 ++--- docs/zh-CN/godot/pool.md | 8 ++--- docs/zh-CN/godot/resource.md | 8 ++--- docs/zh-CN/tutorials/basic/07-summary.md | 8 ++--- docs/zh-CN/tutorials/basic/index.md | 8 ++--- docs/zh-CN/tutorials/coroutine-tutorial.md | 4 +-- docs/zh-CN/tutorials/data-migration.md | 18 +++++------ .../zh-CN/tutorials/functional-programming.md | 14 ++++----- .../zh-CN/tutorials/godot-complete-project.md | 14 ++++----- docs/zh-CN/tutorials/index.md | 16 +++++----- .../tutorials/large-project-organization.md | 20 ++++++------- docs/zh-CN/tutorials/pause-system.md | 18 +++++------ docs/zh-CN/tutorials/resource-management.md | 18 +++++------ docs/zh-CN/tutorials/save-system.md | 18 +++++------ .../zh-CN/tutorials/state-machine-tutorial.md | 18 +++++------ docs/zh-CN/tutorials/unit-testing.md | 8 ++--- 22 files changed, 147 insertions(+), 142 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 7ddf9f2f..3dbd3f72 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,12 +12,12 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-027` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-028` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，本批已收口 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 的 metadata 缺口 + - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，本批已收口 `25` 个 `docs/zh-CN` 页面中的站内链接 `.md` / `index.md` 一致性 - 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明 - - 继续优先处理低风险 metadata 缺口、坏链与 Markdown 结构问题，避免跨模块语义改写 + - 继续优先处理低风险 metadata 缺口、坏链、README 文档入口对齐与 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/` @@ -25,7 +25,7 @@ ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 -- `2026-04-24` 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 batch baseline 时，当前分支累计 diff 为 `0` 个文件；本批 write set 聚焦 `8` 个文档页面与 `2` 个 `ai-plan` 入口文件，预计提交后分支 diff 为 `10 / 75` 个 changed files。 +- `2026-04-24` 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 batch baseline 时，当前分支累计 diff 在 `RP-027` 提交后为 `10` 个文件；本批 write set 额外覆盖 `25` 个 `docs/zh-CN` 页面与 `2` 个 `ai-plan` 入口文件，提交后分支 diff 为 `29 / 75` 个 changed files。 - `2026-04-24` 使用 `$gframework-pr-review` 抓取 PR `#282` 后，确认 latest head commit `982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread；4 条建议均已在本地复核并纳入当前恢复点。 - 本轮 PR follow-up 仅收口仍然成立的 review 项： @@ -33,6 +33,7 @@ - 将 `docs/zh-CN/core/context.md` 的标题本地化为中文读者友好的写法 - 统一 `docs/zh-CN/troubleshooting.md` 中 `/zh-CN/core/architecture` 与 `/zh-CN/faq` 的 `.md` 链接写法 - 本批次补齐了 `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 构建解析分叉。 - `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`、 @@ -74,11 +75,15 @@ - 结果：通过；当前带 frontmatter 的 `docs/zh-CN` 页面已无 `title` / `description` 缺口。 - `2026-04-24` `bun run build`（工作目录：`docs/`） - 结果：通过；首页与基础教程 metadata 补齐后站点仍可正常构建，仅保留既有大 chunk warning。 +- `2026-04-24` `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` 中以 `./`、`../`、`/zh-CN/` 开头且未带扩展名的 Markdown 链接） + - 结果：通过；当前 `docs/zh-CN` 站内 Markdown 链接已无缺失扩展名的命中。 +- `2026-04-24` `bun run build`（工作目录：`docs/`） + - 结果：通过；`25` 个页面的站内链接补齐为显式 `.md` / `index.md` 后站点仍可正常构建，仅保留既有大 chunk warning。 ## 下一步 -1. 推送本批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。 -2. 若继续执行 `$gframework-batch-boot 75`，优先盘点 `docs/zh-CN` 中仍缺完整 frontmatter 的页面，并按模块或教程小批次补齐 metadata。 +1. 若继续执行 `$gframework-batch-boot 75`，优先盘点模块 `README.md`、`docs/index.md` 与文档落地页之间仍未对齐的文档入口、BOM 与旧链接写法。 +2. 推送当前批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。 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`、 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 d0ad6fb2..f82b9464 100644 --- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -2,28 +2,28 @@ ## 2026-04-24 -### 当前恢复点：RP-027 +### 当前恢复点：RP-028 -- 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 `$gframework-batch-boot 75` baseline，确认批次开始时当前分支累计 diff 为 `0` 个文件。 -- 选择“frontmatter metadata 缺口”作为本批次低风险切片，不继续扩大到正文语义改写或跨模块文档重写。 -- 本批次补齐了 `docs/zh-CN/index.md` 的 `description`，以及 `docs/zh-CN/tutorials/basic/01-07.md` 的 `title` / `description`。 +- 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 `$gframework-batch-boot 75` baseline，确认 `RP-027` 提交后的当前分支累计 diff 为 `10` 个文件。 +- 选择“站内 Markdown 链接显式扩展名统一”作为本批次低风险切片，集中处理教程、最佳实践、Core 与 Godot 页面中的目录链接和缺 `.md` 的旧写法。 +- 本批次修改了 `25` 个 `docs/zh-CN` 页面，把 `./`、`../`、`/zh-CN/` 开头的站内 Markdown 链接统一补齐为显式 `.md` 或 `index.md`。 -### 当前决策（RP-027） +### 当前决策（RP-028） -- 当 branch diff 明显低于 `75` 文件阈值时，优先消化低风险 metadata / 链接 / Markdown 结构缺口，避免在同一批次混入高语义成本的文案重写。 +- 当 branch diff 仍显著低于 `75` 文件阈值时，继续优先消化低风险链接规范化和 README / landing page 对齐问题，不在同一批次混入高语义重写。 +- 构建失败优先视为机械链接转换回归，先修复批量规则副作用再继续，而不是带着失效链接进入后续批次。 - active `ai-plan` 入口继续保持轻量，只记录当前恢复点、batch metric、验证结果与下一批候选项。 -- 当前 WSL 会话继续使用显式 `--git-dir` / `--work-tree` 绑定执行 Git，避免 `git.exe` 失效带来的路径问题。 -### 当前验证（RP-027） +### 当前验证（RP-028） -- frontmatter 巡检： - - `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` frontmatter 是否缺 `title` / `description`） - - 结果：通过；当前带 frontmatter 的 `docs/zh-CN` 页面已无 `title` / `description` 缺口。 +- 站内链接巡检： + - `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` 中以 `./`、`../`、`/zh-CN/` 开头且未带扩展名的 Markdown 链接） + - 结果：通过；当前 `docs/zh-CN` 站内 Markdown 链接已无缺失扩展名的命中。 - 站点构建： - `bun run build`（工作目录：`docs/`） - - 结果：通过；首页与基础教程 metadata 补齐后站点仍可正常构建，仅保留既有大 chunk warning。 + - 结果：通过；统一 `25` 个页面的站内链接后站点仍可正常构建，仅保留既有大 chunk warning。 - 当前 stop-condition metric： - - 提交前工作树 write set 为 `10` 个文件（`8` 个文档页面 + `2` 个 `ai-plan` 入口）；本批次提交后分支 diff 将提升为 `10 / 75` 个 changed files。 + - 本批次 write set 为 `27` 个文件（`25` 个文档页面 + `2` 个 `ai-plan` 入口）；本批次提交后分支 diff 为 `29 / 75` 个 changed files。 ### 归档指针 @@ -35,5 +35,5 @@ ### 下一步 -1. 推送本批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。 -2. 若继续执行 `$gframework-batch-boot 75`，优先盘点 `docs/zh-CN` 中仍缺完整 frontmatter 的页面，并按模块或教程小批次补齐 metadata。 +1. 若继续执行 `$gframework-batch-boot 75`，优先盘点模块 `README.md`、`docs/index.md` 与文档落地页之间仍未对齐的文档入口、BOM 与旧链接写法。 +2. 推送本批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。 diff --git a/docs/zh-CN/best-practices/architecture-patterns.md b/docs/zh-CN/best-practices/architecture-patterns.md index f452e972..93d2dd7a 100644 --- a/docs/zh-CN/best-practices/architecture-patterns.md +++ b/docs/zh-CN/best-practices/architecture-patterns.md @@ -3432,12 +3432,12 @@ public void GetPlayerStatsQuery_ShouldReturnCorrectStats() ### 相关资源 -- [架构核心文档](/zh-CN/core/architecture) -- [命令模式文档](/zh-CN/core/command) -- [查询模式文档](/zh-CN/core/query) -- [事件系统文档](/zh-CN/core/events) -- [状态机文档](/zh-CN/core/state-machine) -- [IoC 容器文档](/zh-CN/core/ioc) +- [架构核心文档](/zh-CN/core/architecture.md) +- [命令模式文档](/zh-CN/core/command.md) +- [查询模式文档](/zh-CN/core/query.md) +- [事件系统文档](/zh-CN/core/events.md) +- [状态机文档](/zh-CN/core/state-machine.md) +- [IoC 容器文档](/zh-CN/core/ioc.md) 记住，好的架构不是一蹴而就的，需要持续的学习、实践和改进。 diff --git a/docs/zh-CN/best-practices/mobile-optimization.md b/docs/zh-CN/best-practices/mobile-optimization.md index de515d8c..a8245d99 100644 --- a/docs/zh-CN/best-practices/mobile-optimization.md +++ b/docs/zh-CN/best-practices/mobile-optimization.md @@ -970,10 +970,10 @@ public class DeviceProfiler ## 相关文档 -- [资源管理系统](/zh-CN/core/resource) - 资源管理详细说明 -- [对象池系统](/zh-CN/core/pool) - 对象池优化 -- [协程系统](/zh-CN/core/coroutine) - 异步操作优化 -- [架构模式最佳实践](/zh-CN/best-practices/architecture-patterns) - 架构设计 +- [资源管理系统](/zh-CN/core/resource.md) - 资源管理详细说明 +- [对象池系统](/zh-CN/core/pool.md) - 对象池优化 +- [协程系统](/zh-CN/core/coroutine.md) - 异步操作优化 +- [架构模式最佳实践](/zh-CN/best-practices/architecture-patterns.md) - 架构设计 --- diff --git a/docs/zh-CN/core/resource.md b/docs/zh-CN/core/resource.md index bdf28891..6dbbe792 100644 --- a/docs/zh-CN/core/resource.md +++ b/docs/zh-CN/core/resource.md @@ -501,7 +501,7 @@ Parallel.For(0, 10, i => ## 相关文档 -- [对象池系统](/zh-CN/core/pool) - 结合对象池复用资源 -- [协程系统](/zh-CN/core/coroutine) - 异步加载资源 -- [Godot 扩展](/zh-CN/godot/extensions) - Godot 引擎的资源管理 -- [资源管理最佳实践](/zh-CN/tutorials/resource-management) - 详细教程 +- [对象池系统](/zh-CN/core/pool.md) - 结合对象池复用资源 +- [协程系统](/zh-CN/core/coroutine.md) - 异步加载资源 +- [Godot 扩展](/zh-CN/godot/extensions.md) - Godot 引擎的资源管理 +- [资源管理最佳实践](/zh-CN/tutorials/resource-management.md) - 详细教程 diff --git a/docs/zh-CN/core/state-machine.md b/docs/zh-CN/core/state-machine.md index 63a264f3..8693306e 100644 --- a/docs/zh-CN/core/state-machine.md +++ b/docs/zh-CN/core/state-machine.md @@ -576,7 +576,7 @@ await stateMachine.GoBackAsync(); ## 相关文档 -- [生命周期管理](/zh-CN/core/lifecycle) - 状态的初始化和销毁 -- [事件系统](/zh-CN/core/events) - 状态变更通知 -- [协程系统](/zh-CN/core/coroutine) - 异步状态操作 -- [状态机实现教程](/zh-CN/tutorials/state-machine-tutorial) - 完整示例 +- [生命周期管理](/zh-CN/core/lifecycle.md) - 状态的初始化和销毁 +- [事件系统](/zh-CN/core/events.md) - 状态变更通知 +- [协程系统](/zh-CN/core/coroutine.md) - 异步状态操作 +- [状态机实现教程](/zh-CN/tutorials/state-machine-tutorial.md) - 完整示例 diff --git a/docs/zh-CN/godot/pause.md b/docs/zh-CN/godot/pause.md index 7f40ae46..980fad9a 100644 --- a/docs/zh-CN/godot/pause.md +++ b/docs/zh-CN/godot/pause.md @@ -730,7 +730,7 @@ foreach (var reason in reasons) ## 相关文档 -- [Godot 架构集成](/zh-CN/godot/architecture) - Godot 架构基础 -- [Godot 场景系统](/zh-CN/godot/scene) - Godot 场景集成 -- [Godot UI 系统](/zh-CN/godot/ui) - Godot UI 集成 -- [Godot 扩展](/zh-CN/godot/extensions) - Godot 扩展方法 +- [Godot 架构集成](/zh-CN/godot/architecture.md) - Godot 架构基础 +- [Godot 场景系统](/zh-CN/godot/scene.md) - Godot 场景集成 +- [Godot UI 系统](/zh-CN/godot/ui.md) - Godot UI 集成 +- [Godot 扩展](/zh-CN/godot/extensions.md) - Godot 扩展方法 diff --git a/docs/zh-CN/godot/pool.md b/docs/zh-CN/godot/pool.md index 98528b43..de906426 100644 --- a/docs/zh-CN/godot/pool.md +++ b/docs/zh-CN/godot/pool.md @@ -678,7 +678,7 @@ GD.Print($"使用池: {stopwatch.ElapsedMilliseconds}ms"); ## 相关文档 -- [对象池系统](/zh-CN/core/pool) - 核心对象池实现 -- [Godot 架构集成](/zh-CN/godot/architecture) - Godot 架构基础 -- [Godot 场景系统](/zh-CN/godot/scene) - Godot 场景管理 -- [性能优化](/zh-CN/core/pool) - 性能优化最佳实践 +- [对象池系统](/zh-CN/core/pool.md) - 核心对象池实现 +- [Godot 架构集成](/zh-CN/godot/architecture.md) - Godot 架构基础 +- [Godot 场景系统](/zh-CN/godot/scene.md) - Godot 场景管理 +- [性能优化](/zh-CN/core/pool.md) - 性能优化最佳实践 diff --git a/docs/zh-CN/godot/resource.md b/docs/zh-CN/godot/resource.md index 6bcb7fd8..7fb78e74 100644 --- a/docs/zh-CN/godot/resource.md +++ b/docs/zh-CN/godot/resource.md @@ -631,7 +631,7 @@ public class LazyResourceRepository ## 相关文档 -- [数据与存档系统](/zh-CN/game/data) - 数据持久化 -- [Godot 架构集成](/zh-CN/godot/architecture) - Godot 架构基础 -- [Godot 场景系统](/zh-CN/godot/scene) - 场景资源管理 -- [资源管理系统](/zh-CN/core/resource) - 核心资源管理 +- [数据与存档系统](/zh-CN/game/data.md) - 数据持久化 +- [Godot 架构集成](/zh-CN/godot/architecture.md) - Godot 架构基础 +- [Godot 场景系统](/zh-CN/godot/scene.md) - 场景资源管理 +- [资源管理系统](/zh-CN/core/resource.md) - 核心资源管理 diff --git a/docs/zh-CN/tutorials/basic/07-summary.md b/docs/zh-CN/tutorials/basic/07-summary.md index 9069a6b6..6576a175 100644 --- a/docs/zh-CN/tutorials/basic/07-summary.md +++ b/docs/zh-CN/tutorials/basic/07-summary.md @@ -646,10 +646,10 @@ public override void _Process(double delta) ### 推荐资源 - **GFramework 文档**： - - [Core 核心框架](../../core/) - - [Game 游戏模块](../../game/) - - [Godot 集成](../../godot/) - - [源码生成器](../../source-generators/) + - [Core 核心框架](../../core/index.md) + - [Game 游戏模块](../../game/index.md) + - [Godot 集成](../../godot/index.md) + - [源码生成器](../../source-generators/index.md) - **设计模式**： - 命令模式（Command Pattern） diff --git a/docs/zh-CN/tutorials/basic/index.md b/docs/zh-CN/tutorials/basic/index.md index 00a34f20..7e2cc085 100644 --- a/docs/zh-CN/tutorials/basic/index.md +++ b/docs/zh-CN/tutorials/basic/index.md @@ -173,10 +173,10 @@ description: 从零开始串联环境准备、项目搭建与核心概念的基 ## 🔗 相关资源 -- [GFramework 文档首页](../../) -- [Core 核心框架](../../core/) -- [Godot 集成](../../godot/) -- [源码生成器](../../source-generators/) +- [GFramework 文档首页](../../index.md) +- [Core 核心框架](../../core/index.md) +- [Godot 集成](../../godot/index.md) +- [源码生成器](../../source-generators/index.md) ## ❓ 遇到问题？ diff --git a/docs/zh-CN/tutorials/coroutine-tutorial.md b/docs/zh-CN/tutorials/coroutine-tutorial.md index 30000d15..8e11eafa 100644 --- a/docs/zh-CN/tutorials/coroutine-tutorial.md +++ b/docs/zh-CN/tutorials/coroutine-tutorial.md @@ -188,5 +188,5 @@ BlinkCoroutine() ## 下一步 -- Core 侧更完整的 API 说明见 [Core 协程系统](/zh-CN/core/coroutine) -- Godot 集成细节见 [Godot 协程系统](/zh-CN/godot/coroutine) +- Core 侧更完整的 API 说明见 [Core 协程系统](/zh-CN/core/coroutine.md) +- Godot 集成细节见 [Godot 协程系统](/zh-CN/godot/coroutine.md) diff --git a/docs/zh-CN/tutorials/data-migration.md b/docs/zh-CN/tutorials/data-migration.md index 3c21c736..0c04df53 100644 --- a/docs/zh-CN/tutorials/data-migration.md +++ b/docs/zh-CN/tutorials/data-migration.md @@ -20,9 +20,9 @@ description: 学习如何实现数据版本迁移系统，处理不同版本间 - 已安装 GFramework.Game NuGet 包 - 了解 C# 基础语法和接口实现 -- 阅读过[快速开始](/zh-CN/getting-started/quick-start) -- 了解[数据与存档系统](/zh-CN/game/data) -- 建议先完成[实现存档系统](/zh-CN/tutorials/save-system)教程 +- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md) +- 了解[数据与存档系统](/zh-CN/game/data.md) +- 建议先完成[实现存档系统](/zh-CN/tutorials/save-system.md)教程 ## 为什么需要数据迁移 @@ -647,9 +647,9 @@ MyGame/ 恭喜！你已经实现了一个完整的数据版本迁移系统。接下来可以学习： -- [实现存档系统](/zh-CN/tutorials/save-system) - 结合存档系统使用迁移 -- [Godot 完整项目搭建](/zh-CN/tutorials/godot-complete-project) - 在实际项目中应用 -- [数据与存档系统](/zh-CN/game/data) - 深入了解数据系统 +- [实现存档系统](/zh-CN/tutorials/save-system.md) - 结合存档系统使用迁移 +- [Godot 完整项目搭建](/zh-CN/tutorials/godot-complete-project.md) - 在实际项目中应用 +- [数据与存档系统](/zh-CN/game/data.md) - 深入了解数据系统 ## 最佳实践 @@ -780,6 +780,6 @@ public async Task> MigrateBatchAsync( ## 相关文档 -- [数据与存档系统](/zh-CN/game/data) - 数据系统详细说明 -- [实现存档系统](/zh-CN/tutorials/save-system) - 存档系统教程 -- [架构系统](/zh-CN/core/architecture) - 架构设计原则 +- [数据与存档系统](/zh-CN/game/data.md) - 数据系统详细说明 +- [实现存档系统](/zh-CN/tutorials/save-system.md) - 存档系统教程 +- [架构系统](/zh-CN/core/architecture.md) - 架构设计原则 diff --git a/docs/zh-CN/tutorials/functional-programming.md b/docs/zh-CN/tutorials/functional-programming.md index bd7a2bf1..121cbd81 100644 --- a/docs/zh-CN/tutorials/functional-programming.md +++ b/docs/zh-CN/tutorials/functional-programming.md @@ -20,7 +20,7 @@ description: 学习如何在实际项目中使用 Option、Result 和管道操 - 已安装 GFramework.Core NuGet 包 - 了解 C# 基础语法和泛型 -- 阅读过[快速开始](/zh-CN/getting-started/quick-start) +- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md) - 了解 Lambda 表达式和 LINQ ## 步骤 1：使用 Option 处理可空值 @@ -811,12 +811,12 @@ class Program 恭喜！你已经掌握了函数式编程的核心技术。接下来可以学习： -- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 结合函数式编程和协程 -- [实现状态机](/zh-CN/tutorials/state-machine-tutorial) - 在状态机中应用函数式模式 -- [资源管理最佳实践](/zh-CN/tutorials/resource-management) - 使用 Result 处理资源加载 +- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 结合函数式编程和协程 +- [实现状态机](/zh-CN/tutorials/state-machine-tutorial.md) - 在状态机中应用函数式模式 +- [资源管理最佳实践](/zh-CN/tutorials/resource-management.md) - 使用 Result 处理资源加载 ## 相关文档 -- [扩展方法](/zh-CN/core/extensions) - 更多函数式扩展方法 -- [架构组件](/zh-CN/core/architecture) - 在架构中使用函数式编程 -- [最佳实践](/zh-CN/best-practices/architecture-patterns) - 函数式编程最佳实践 +- [扩展方法](/zh-CN/core/extensions.md) - 更多函数式扩展方法 +- [架构组件](/zh-CN/core/architecture.md) - 在架构中使用函数式编程 +- [最佳实践](/zh-CN/best-practices/architecture-patterns.md) - 函数式编程最佳实践 diff --git a/docs/zh-CN/tutorials/godot-complete-project.md b/docs/zh-CN/tutorials/godot-complete-project.md index 5c0594ac..3545827c 100644 --- a/docs/zh-CN/tutorials/godot-complete-project.md +++ b/docs/zh-CN/tutorials/godot-complete-project.md @@ -22,9 +22,9 @@ description: 从零开始使用 GFramework 构建一个完整的 Godot 游戏项 - 已安装 .NET SDK 8.0+ - 了解 C# 和 Godot 基础 - 阅读过前面的教程： - - [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - - [实现状态机](/zh-CN/tutorials/state-machine-tutorial) - - [实现存档系统](/zh-CN/tutorials/save-system) + - [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) + - [实现状态机](/zh-CN/tutorials/state-machine-tutorial.md) + - [实现存档系统](/zh-CN/tutorials/save-system.md) ## 项目概述 @@ -805,7 +805,7 @@ public partial class GameScene : Node2D, IController ## 相关文档 -- [Godot 架构集成](/zh-CN/godot/architecture) - 架构详细说明 -- [Godot 场景系统](/zh-CN/godot/scene) - 场景管理 -- [Godot UI 系统](/zh-CN/godot/ui) - UI 管理 -- [Godot 扩展](/zh-CN/godot/extensions) - 扩展功能 +- [Godot 架构集成](/zh-CN/godot/architecture.md) - 架构详细说明 +- [Godot 场景系统](/zh-CN/godot/scene.md) - 场景管理 +- [Godot UI 系统](/zh-CN/godot/ui.md) - UI 管理 +- [Godot 扩展](/zh-CN/godot/extensions.md) - 扩展功能 diff --git a/docs/zh-CN/tutorials/index.md b/docs/zh-CN/tutorials/index.md index 205d881d..0646beb7 100644 --- a/docs/zh-CN/tutorials/index.md +++ b/docs/zh-CN/tutorials/index.md @@ -9,7 +9,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习 ## 📚 可用教程 -### [基础教程](./basic/) +### [基础教程](./basic/index.md) > 从零开始学习 GFramework，通过构建一个完整的计数器应用，逐步掌握框架的核心概念。 @@ -169,7 +169,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习 ### 善用资源 -- **查阅文档**：结合 [Core 核心框架](../core/) 和 [Godot 集成](../godot/) 文档 +- **查阅文档**：结合 [Core 核心框架](../core/index.md) 和 [Godot 集成](../godot/index.md) 文档 - **查看示例**：参考框架附带的示例项目 - **社区交流**：遇到问题时查看 GitHub Issues 或参与讨论 @@ -193,11 +193,11 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习 ## 🔗 相关资源 -- [入门指南](../getting-started/) - 快速了解框架和安装配置 -- [Core 核心框架](../core/) - 深入学习核心概念 -- [Game 模块](../game/) - 游戏特定功能文档 -- [Godot 集成](../godot/) - Godot 特定功能参考 -- [源码生成器](../source-generators/) - 自动化代码生成工具 +- [入门指南](../getting-started/index.md) - 快速了解框架和安装配置 +- [Core 核心框架](../core/index.md) - 深入学习核心概念 +- [Game 模块](../game/index.md) - 游戏特定功能文档 +- [Godot 集成](../godot/index.md) - Godot 特定功能参考 +- [源码生成器](../source-generators/index.md) - 自动化代码生成工具 --- @@ -236,7 +236,7 @@ A: 根据学习深度不同：
-[开始基础教程 →](./basic/) +[开始基础教程 →](./basic/index.md)
diff --git a/docs/zh-CN/tutorials/large-project-organization.md b/docs/zh-CN/tutorials/large-project-organization.md index 36e8c85f..d2ff8f7e 100644 --- a/docs/zh-CN/tutorials/large-project-organization.md +++ b/docs/zh-CN/tutorials/large-project-organization.md @@ -20,8 +20,8 @@ description: 学习如何使用 GFramework 组织和管理大型游戏项目 - 已安装 GFramework.Core 和 GFramework.Game NuGet 包 - 了解 C# 基础语法和面向对象编程 -- 阅读过[快速开始](/zh-CN/getting-started/quick-start) -- 了解[架构组件](/zh-CN/core/architecture)和[模块系统](/zh-CN/core/architecture#模块系统) +- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md) +- 了解[架构组件](/zh-CN/core/architecture.md)和[模块系统](/zh-CN/core/architecture.md#模块系统) ## 步骤 1: 项目结构设计 @@ -1628,14 +1628,14 @@ namespace MyGame 恭喜!你已经掌握了大型项目的组织方法。接下来可以学习: -- [Godot 完整项目](/zh-CN/tutorials/godot-complete-project) - 在 Godot 中应用这些原则 -- [资源管理最佳实践](/zh-CN/tutorials/resource-management) - 管理大型项目的资源 -- [实现存档系统](/zh-CN/tutorials/save-system) - 保存复杂的游戏状态 -- [架构模式最佳实践](/zh-CN/best-practices/architecture-patterns) - 高级架构模式 +- [Godot 完整项目](/zh-CN/tutorials/godot-complete-project.md) - 在 Godot 中应用这些原则 +- [资源管理最佳实践](/zh-CN/tutorials/resource-management.md) - 管理大型项目的资源 +- [实现存档系统](/zh-CN/tutorials/save-system.md) - 保存复杂的游戏状态 +- [架构模式最佳实践](/zh-CN/best-practices/architecture-patterns.md) - 高级架构模式 ## 相关文档 -- [架构组件](/zh-CN/core/architecture) - 架构系统详解 -- [模块系统](/zh-CN/core/architecture#模块系统) - 模块化设计 -- [依赖注入](/zh-CN/core/ioc) - IoC 容器使用 -- [最佳实践](/zh-CN/best-practices/) - 开发最佳实践 +- [架构组件](/zh-CN/core/architecture.md) - 架构系统详解 +- [模块系统](/zh-CN/core/architecture.md#模块系统) - 模块化设计 +- [依赖注入](/zh-CN/core/ioc.md) - IoC 容器使用 +- [最佳实践](/zh-CN/best-practices/index.md) - 开发最佳实践 diff --git a/docs/zh-CN/tutorials/pause-system.md b/docs/zh-CN/tutorials/pause-system.md index 35dc47bd..8022b76e 100644 --- a/docs/zh-CN/tutorials/pause-system.md +++ b/docs/zh-CN/tutorials/pause-system.md @@ -20,8 +20,8 @@ description: 学习如何使用暂停系统实现多层暂停管理和游戏流 - 已安装 GFramework.Core NuGet 包 - 了解 C# 基础语法和接口实现 -- 阅读过[快速开始](/zh-CN/getting-started/quick-start) -- 了解[架构组件](/zh-CN/core/architecture)基础 +- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md) +- 了解[架构组件](/zh-CN/core/architecture.md)基础 ## 步骤 1：注册暂停管理器 @@ -1120,14 +1120,14 @@ class Program 恭喜！你已经掌握了暂停系统的使用。接下来可以学习： -- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 在暂停状态下控制协程 -- [实现状态机](/zh-CN/tutorials/state-machine-tutorial) - 结合状态机管理游戏流程 -- [事件系统](/zh-CN/core/events) - 使用事件响应暂停状态变化 +- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 在暂停状态下控制协程 +- [实现状态机](/zh-CN/tutorials/state-machine-tutorial.md) - 结合状态机管理游戏流程 +- [事件系统](/zh-CN/core/events.md) - 使用事件响应暂停状态变化 ## 相关文档 -- [架构组件](/zh-CN/core/architecture) - 架构基础 -- [Utility 层](/zh-CN/core/utility) - Utility 详细说明 -- [生命周期管理](/zh-CN/core/lifecycle) - 组件生命周期 -- [扩展方法](/zh-CN/core/extensions) - 便捷的扩展方法 +- [架构组件](/zh-CN/core/architecture.md) - 架构基础 +- [Utility 层](/zh-CN/core/utility.md) - Utility 详细说明 +- [生命周期管理](/zh-CN/core/lifecycle.md) - 组件生命周期 +- [扩展方法](/zh-CN/core/extensions.md) - 便捷的扩展方法 diff --git a/docs/zh-CN/tutorials/resource-management.md b/docs/zh-CN/tutorials/resource-management.md index a694761e..52f59464 100644 --- a/docs/zh-CN/tutorials/resource-management.md +++ b/docs/zh-CN/tutorials/resource-management.md @@ -20,8 +20,8 @@ description: 学习如何高效管理游戏资源，避免内存泄漏和性能 - 已安装 GFramework.Core NuGet 包 - 了解 C# 基础语法和 async/await -- 阅读过[快速开始](/zh-CN/getting-started/quick-start) -- 了解[协程系统](/zh-CN/core/coroutine) +- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md) +- 了解[协程系统](/zh-CN/core/coroutine.md) ## 步骤 1：创建资源类型和加载器 @@ -802,13 +802,13 @@ MyGame/ 恭喜！你已经掌握了资源管理的最佳实践。接下来可以学习： -- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 在协程中加载资源 -- [实现状态机](/zh-CN/tutorials/state-machine-tutorial) - 在状态切换时管理资源 -- [实现存档系统](/zh-CN/tutorials/save-system) - 保存和加载游戏数据 +- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 在协程中加载资源 +- [实现状态机](/zh-CN/tutorials/state-machine-tutorial.md) - 在状态切换时管理资源 +- [实现存档系统](/zh-CN/tutorials/save-system.md) - 保存和加载游戏数据 ## 相关文档 -- [资源管理系统](/zh-CN/core/resource) - 资源系统详细说明 -- [对象池系统](/zh-CN/core/pool) - 结合对象池复用资源 -- [协程系统](/zh-CN/core/coroutine) - 异步加载资源 -- [System 层](/zh-CN/core/system) - System 详细说明 +- [资源管理系统](/zh-CN/core/resource.md) - 资源系统详细说明 +- [对象池系统](/zh-CN/core/pool.md) - 结合对象池复用资源 +- [协程系统](/zh-CN/core/coroutine.md) - 异步加载资源 +- [System 层](/zh-CN/core/system.md) - System 详细说明 diff --git a/docs/zh-CN/tutorials/save-system.md b/docs/zh-CN/tutorials/save-system.md index dbd264d0..f6782998 100644 --- a/docs/zh-CN/tutorials/save-system.md +++ b/docs/zh-CN/tutorials/save-system.md @@ -20,8 +20,8 @@ description: 学习如何实现完整的游戏存档系统，支持多槽位和 - 已安装 GFramework.Game NuGet 包 - 了解 C# 基础语法和 async/await -- 阅读过[快速开始](/zh-CN/getting-started/quick-start) -- 了解[数据与存档系统](/zh-CN/game/data) +- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md) +- 了解[数据与存档系统](/zh-CN/game/data.md) ## 步骤 1：定义存档数据结构 @@ -954,13 +954,13 @@ MyGame/ 恭喜！你已经实现了一个完整的存档系统。接下来可以学习： -- [Godot 完整项目搭建](/zh-CN/tutorials/godot-complete-project) - 在 Godot 中使用存档系统 -- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 异步加载存档 -- [数据与存档系统](/zh-CN/game/data) - 数据系统详细说明 +- [Godot 完整项目搭建](/zh-CN/tutorials/godot-complete-project.md) - 在 Godot 中使用存档系统 +- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 异步加载存档 +- [数据与存档系统](/zh-CN/game/data.md) - 数据系统详细说明 ## 相关文档 -- [数据与存档系统](/zh-CN/game/data) - 数据系统详细说明 -- [对象池系统](/zh-CN/core/pool) - 结合对象池复用资源 -- [协程系统](/zh-CN/core/coroutine) - 异步加载资源 -- [System 层](/zh-CN/core/system) - System 详细说明 \ No newline at end of file +- [数据与存档系统](/zh-CN/game/data.md) - 数据系统详细说明 +- [对象池系统](/zh-CN/core/pool.md) - 结合对象池复用资源 +- [协程系统](/zh-CN/core/coroutine.md) - 异步加载资源 +- [System 层](/zh-CN/core/system.md) - System 详细说明 \ No newline at end of file diff --git a/docs/zh-CN/tutorials/state-machine-tutorial.md b/docs/zh-CN/tutorials/state-machine-tutorial.md index bbea6b5a..587dd37e 100644 --- a/docs/zh-CN/tutorials/state-machine-tutorial.md +++ b/docs/zh-CN/tutorials/state-machine-tutorial.md @@ -20,8 +20,8 @@ description: 学习如何使用状态机系统管理游戏状态和场景切换 - 已安装 GFramework.Core NuGet 包 - 了解 C# 基础语法和 async/await -- 阅读过[快速开始](/zh-CN/getting-started/quick-start) -- 了解[生命周期管理](/zh-CN/core/lifecycle) +- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md) +- 了解[生命周期管理](/zh-CN/core/lifecycle.md) ## 步骤 1：定义游戏状态 @@ -734,13 +734,13 @@ MyGame/ 恭喜！你已经掌握了状态机系统的使用。接下来可以学习： -- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 在状态中使用协程 -- [资源管理最佳实践](/zh-CN/tutorials/resource-management) - 在加载状态中管理资源 -- [实现存档系统](/zh-CN/tutorials/save-system) - 保存和恢复游戏状态 +- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 在状态中使用协程 +- [资源管理最佳实践](/zh-CN/tutorials/resource-management.md) - 在加载状态中管理资源 +- [实现存档系统](/zh-CN/tutorials/save-system.md) - 保存和恢复游戏状态 ## 相关文档 -- [状态机系统](/zh-CN/core/state-machine) - 状态机详细说明 -- [生命周期管理](/zh-CN/core/lifecycle) - 组件生命周期 -- [System 层](/zh-CN/core/system) - System 详细说明 -- [架构组件](/zh-CN/core/architecture) - 架构基础 +- [状态机系统](/zh-CN/core/state-machine.md) - 状态机详细说明 +- [生命周期管理](/zh-CN/core/lifecycle.md) - 组件生命周期 +- [System 层](/zh-CN/core/system.md) - System 详细说明 +- [架构组件](/zh-CN/core/architecture.md) - 架构基础 diff --git a/docs/zh-CN/tutorials/unit-testing.md b/docs/zh-CN/tutorials/unit-testing.md index fcb7022e..7011d539 100644 --- a/docs/zh-CN/tutorials/unit-testing.md +++ b/docs/zh-CN/tutorials/unit-testing.md @@ -22,8 +22,8 @@ description: 学习如何为 GFramework 项目编写单元测试 - 已安装 .NET SDK 8.0 或更高版本 - 了解 C# 基础语法 - 熟悉 xUnit 或 NUnit 测试框架 -- 阅读过[快速开始](/zh-CN/getting-started/quick-start) -- 了解[架构系统](/zh-CN/core/architecture) +- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md) +- 了解[架构系统](/zh-CN/core/architecture.md) ## 步骤 1：创建测试项目 @@ -1143,5 +1143,5 @@ public void CalculateBonus_Should_Return_Double(int input, int expected) - [NUnit 官方文档](https://docs.nunit.org/) - [Moq 快速入门](https://github.com/moq/moq4/wiki/Quickstart) -- [架构设计模式](/zh-CN/best-practices/architecture-patterns) -- [性能优化最佳实践](/zh-CN/best-practices/performance) +- [架构设计模式](/zh-CN/best-practices/architecture-patterns.md) +- [性能优化最佳实践](/zh-CN/best-practices/performance.md) From 77540c07f0890cc05b10a849722c87b8bed8f561 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Fri, 24 Apr 2026 13:23:15 +0800 Subject: [PATCH 3/4] =?UTF-8?q?docs(readme):=20=E5=AF=B9=E9=BD=90=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=85=A5=E5=8F=A3=E6=A0=87=E7=AD=BE=E4=B8=8E=E8=90=BD?= =?UTF-8?q?=E5=9C=B0=E9=A1=B5=E5=85=83=E6=95=B0=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新模块 README、仓库根 README 与中文落地页的 reader-facing 文档入口标签 - 补充 docs 语言落地页 metadata 并校正文档治理 topic 的恢复点与阈值指标 --- GFramework.Core.Abstractions/README.md | 2 +- GFramework.Core/README.md | 2 +- GFramework.Cqrs.Abstractions/README.md | 4 +-- GFramework.Cqrs/README.md | 4 +-- GFramework.Game.Abstractions/README.md | 16 ++++----- GFramework.Game/README.md | 36 +++++++++---------- GFramework.Godot.SourceGenerators/README.md | 18 +++++----- GFramework.Godot/README.md | 16 ++++----- README.md | 34 +++++++++--------- ...ation-full-coverage-governance-tracking.md | 13 ++++--- ...entation-full-coverage-governance-trace.md | 27 +++++++------- docs/index.md | 6 ++-- docs/zh-CN/abstractions/core-abstractions.md | 4 +-- .../abstractions/ecs-arch-abstractions.md | 4 +-- docs/zh-CN/abstractions/game-abstractions.md | 4 +-- docs/zh-CN/api-reference/index.md | 10 +++--- docs/zh-CN/core/cqrs.md | 2 +- docs/zh-CN/core/index.md | 8 ++--- docs/zh-CN/ecs/arch.md | 2 +- docs/zh-CN/game/index.md | 4 +-- docs/zh-CN/game/scene.md | 4 +-- docs/zh-CN/game/ui.md | 4 +-- docs/zh-CN/getting-started/index.md | 6 ++-- docs/zh-CN/godot/signal.md | 2 +- ...register-exported-collections-generator.md | 2 +- .../bind-node-signal-generator.md | 2 +- .../context-aware-generator.md | 2 +- .../source-generators/get-node-generator.md | 2 +- .../godot-project-generator.md | 2 +- docs/zh-CN/source-generators/index.md | 8 ++--- .../source-generators/priority-generator.md | 2 +- 31 files changed, 127 insertions(+), 125 deletions(-) diff --git a/GFramework.Core.Abstractions/README.md b/GFramework.Core.Abstractions/README.md index d6a9753b..ce390fa1 100644 --- a/GFramework.Core.Abstractions/README.md +++ b/GFramework.Core.Abstractions/README.md @@ -49,7 +49,7 @@ XML 注释。这里记录的是类型族级基线，成员级契约细节仍需 | `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `7/7` 个类型声明已带 XML 注释 | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom`、`ISerializer`、`IStorage` | | `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `19/19` 个类型声明已带 XML 注释 | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` | -完整 inventory 与阅读顺序见 `docs/zh-CN/abstractions/core-abstractions.md`。 +完整 inventory 与阅读顺序见 [Core 抽象层说明](../docs/zh-CN/abstractions/core-abstractions.md)。 ## 采用建议 diff --git a/GFramework.Core/README.md b/GFramework.Core/README.md index 61e89a8a..7f8b9f14 100644 --- a/GFramework.Core/README.md +++ b/GFramework.Core/README.md @@ -75,7 +75,7 @@ XML 注释。这里先保留阅读基线，成员级 ```` / ```` | `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `31/31` 个类型声明已带 XML 注释 | `ConsoleLogger`、`LocalizationManager`、`ConfigurationManager`、`DefaultEnvironment`、`MicrosoftDiContainer` | | `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `34/34` 个类型声明已带 XML 注释 | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result` | -完整的模块化阅读顺序和 inventory 说明见 `docs/zh-CN/core/index.md`。 +完整的模块化阅读顺序和 inventory 说明见 [Core 栏目](../docs/zh-CN/core/index.md)。 ## 最小接入路径 diff --git a/GFramework.Cqrs.Abstractions/README.md b/GFramework.Cqrs.Abstractions/README.md index 38166b8b..4bb1d8ff 100644 --- a/GFramework.Cqrs.Abstractions/README.md +++ b/GFramework.Cqrs.Abstractions/README.md @@ -97,5 +97,5 @@ public sealed class GetPlayerProfileHandler ## 文档入口 -- 运行时与整体接入说明：`docs/zh-CN/core/cqrs.md` -- 如果你需要默认实现而不是契约层，请看 `GFramework.Cqrs/README.md` +- 运行时与整体接入说明：[CQRS 栏目](../docs/zh-CN/core/cqrs.md) +- 如果你需要默认实现而不是契约层，请看 [GFramework.Cqrs README](../GFramework.Cqrs/README.md) diff --git a/GFramework.Cqrs/README.md b/GFramework.Cqrs/README.md index 656a90d3..86e3f782 100644 --- a/GFramework.Cqrs/README.md +++ b/GFramework.Cqrs/README.md @@ -150,5 +150,5 @@ var playerId = await this.SendAsync(new CreatePlayerCommand(new CreatePlayerInpu ## 文档入口 -- 总体文档：`docs/zh-CN/core/cqrs.md` -- 契约层说明：`GFramework.Cqrs.Abstractions/README.md` +- 总体文档：[CQRS 栏目](../docs/zh-CN/core/cqrs.md) +- 契约层说明：[GFramework.Cqrs.Abstractions README](../GFramework.Cqrs.Abstractions/README.md) diff --git a/GFramework.Game.Abstractions/README.md b/GFramework.Game.Abstractions/README.md index d69c7c10..9439de79 100644 --- a/GFramework.Game.Abstractions/README.md +++ b/GFramework.Game.Abstractions/README.md @@ -236,14 +236,14 @@ public sealed class ContinueGameCommandHandler 虽然大部分详细文档写在 `GFramework.Game` 侧，但阅读顺序仍然适用于本包： -- 游戏模块总览：[docs/zh-CN/game/index.md](../docs/zh-CN/game/index.md) -- 内容配置系统：[docs/zh-CN/game/config-system.md](../docs/zh-CN/game/config-system.md) -- 数据与存档：[docs/zh-CN/game/data.md](../docs/zh-CN/game/data.md) -- 设置系统：[docs/zh-CN/game/setting.md](../docs/zh-CN/game/setting.md) -- 存储系统：[docs/zh-CN/game/storage.md](../docs/zh-CN/game/storage.md) -- 序列化系统：[docs/zh-CN/game/serialization.md](../docs/zh-CN/game/serialization.md) -- 场景系统：[docs/zh-CN/game/scene.md](../docs/zh-CN/game/scene.md) -- UI 系统：[docs/zh-CN/game/ui.md](../docs/zh-CN/game/ui.md) +- 游戏模块总览：[Game 模块总览](../docs/zh-CN/game/index.md) +- 内容配置系统：[内容配置系统](../docs/zh-CN/game/config-system.md) +- 数据与存档：[数据与存档系统](../docs/zh-CN/game/data.md) +- 设置系统：[设置系统](../docs/zh-CN/game/setting.md) +- 存储系统：[存储系统](../docs/zh-CN/game/storage.md) +- 序列化系统：[序列化系统](../docs/zh-CN/game/serialization.md) +- 场景系统：[场景系统](../docs/zh-CN/game/scene.md) +- UI 系统：[UI 系统](../docs/zh-CN/game/ui.md) ## 选择建议 diff --git a/GFramework.Game/README.md b/GFramework.Game/README.md index b4e8b8c2..b5d026ec 100644 --- a/GFramework.Game/README.md +++ b/GFramework.Game/README.md @@ -57,8 +57,8 @@ 对应文档： -- [docs/zh-CN/game/config-system.md](../docs/zh-CN/game/config-system.md) -- [docs/zh-CN/game/index.md](../docs/zh-CN/game/index.md) +- [内容配置系统](../docs/zh-CN/game/config-system.md) +- [Game 模块总览](../docs/zh-CN/game/index.md) ### `Data/` @@ -81,8 +81,8 @@ 对应文档： -- [docs/zh-CN/game/data.md](../docs/zh-CN/game/data.md) -- [docs/zh-CN/game/setting.md](../docs/zh-CN/game/setting.md) +- [数据与存档系统](../docs/zh-CN/game/data.md) +- [设置系统](../docs/zh-CN/game/setting.md) ### `Setting/` @@ -105,7 +105,7 @@ 对应文档： -- [docs/zh-CN/game/setting.md](../docs/zh-CN/game/setting.md) +- [设置系统](../docs/zh-CN/game/setting.md) ### `Storage/` @@ -121,7 +121,7 @@ 对应文档： -- [docs/zh-CN/game/storage.md](../docs/zh-CN/game/storage.md) +- [存储系统](../docs/zh-CN/game/storage.md) - [GFramework.Game/Storage/ReadMe.md](./Storage/ReadMe.md) ### `Serializer/` @@ -134,7 +134,7 @@ 对应文档： -- [docs/zh-CN/game/serialization.md](../docs/zh-CN/game/serialization.md) +- [序列化系统](../docs/zh-CN/game/serialization.md) ### `Scene/` 与 `UI/` @@ -157,8 +157,8 @@ 对应文档： -- [docs/zh-CN/game/scene.md](../docs/zh-CN/game/scene.md) -- [docs/zh-CN/game/ui.md](../docs/zh-CN/game/ui.md) +- [场景系统](../docs/zh-CN/game/scene.md) +- [UI 系统](../docs/zh-CN/game/ui.md) ### `Routing/` 与 `State/` @@ -293,7 +293,7 @@ var registry = bootstrap.Registry; 这一能力几乎总是与 source generators 绑定使用。目录、schema、生成器与热重载约定请直接看： -- [docs/zh-CN/game/config-system.md](../docs/zh-CN/game/config-system.md) +- [内容配置系统](../docs/zh-CN/game/config-system.md) ### 4. 接入 Scene / UI 路由 @@ -342,14 +342,14 @@ public sealed class MyUiRouter : UiRouterBase ## 文档入口 -- 游戏模块总览：[docs/zh-CN/game/index.md](../docs/zh-CN/game/index.md) -- 内容配置系统：[docs/zh-CN/game/config-system.md](../docs/zh-CN/game/config-system.md) -- 数据与存档：[docs/zh-CN/game/data.md](../docs/zh-CN/game/data.md) -- 设置系统：[docs/zh-CN/game/setting.md](../docs/zh-CN/game/setting.md) -- 存储系统：[docs/zh-CN/game/storage.md](../docs/zh-CN/game/storage.md) -- 序列化系统：[docs/zh-CN/game/serialization.md](../docs/zh-CN/game/serialization.md) -- 场景系统：[docs/zh-CN/game/scene.md](../docs/zh-CN/game/scene.md) -- UI 系统：[docs/zh-CN/game/ui.md](../docs/zh-CN/game/ui.md) +- 游戏模块总览：[Game 模块总览](../docs/zh-CN/game/index.md) +- 内容配置系统：[内容配置系统](../docs/zh-CN/game/config-system.md) +- 数据与存档：[数据与存档系统](../docs/zh-CN/game/data.md) +- 设置系统：[设置系统](../docs/zh-CN/game/setting.md) +- 存储系统：[存储系统](../docs/zh-CN/game/storage.md) +- 序列化系统：[序列化系统](../docs/zh-CN/game/serialization.md) +- 场景系统：[场景系统](../docs/zh-CN/game/scene.md) +- UI 系统：[UI 系统](../docs/zh-CN/game/ui.md) ## 什么时候不该直接依赖本包 diff --git a/GFramework.Godot.SourceGenerators/README.md b/GFramework.Godot.SourceGenerators/README.md index 84cd6d95..c358118e 100644 --- a/GFramework.Godot.SourceGenerators/README.md +++ b/GFramework.Godot.SourceGenerators/README.md @@ -183,15 +183,15 @@ public partial class MainMenu : Control ## 文档入口 -- 生成器总览：[docs/zh-CN/source-generators/index.md](../docs/zh-CN/source-generators/index.md) -- Godot 项目元数据：[docs/zh-CN/source-generators/godot-project-generator.md](../docs/zh-CN/source-generators/godot-project-generator.md) -- `GetNode`：[docs/zh-CN/source-generators/get-node-generator.md](../docs/zh-CN/source-generators/get-node-generator.md) -- `BindNodeSignal`：[docs/zh-CN/source-generators/bind-node-signal-generator.md](../docs/zh-CN/source-generators/bind-node-signal-generator.md) -- `AutoScene`：[docs/zh-CN/source-generators/auto-scene-generator.md](../docs/zh-CN/source-generators/auto-scene-generator.md) -- `AutoUiPage`：[docs/zh-CN/source-generators/auto-ui-page-generator.md](../docs/zh-CN/source-generators/auto-ui-page-generator.md) -- `AutoRegisterExportedCollections`：[docs/zh-CN/source-generators/auto-register-exported-collections-generator.md](../docs/zh-CN/source-generators/auto-register-exported-collections-generator.md) +- 生成器总览：[源码生成器总览](../docs/zh-CN/source-generators/index.md) +- Godot 项目元数据：[Godot 项目生成器](../docs/zh-CN/source-generators/godot-project-generator.md) +- `GetNode`：[GetNode 生成器](../docs/zh-CN/source-generators/get-node-generator.md) +- `BindNodeSignal`：[BindNodeSignal 生成器](../docs/zh-CN/source-generators/bind-node-signal-generator.md) +- `AutoScene`：[AutoScene 生成器](../docs/zh-CN/source-generators/auto-scene-generator.md) +- `AutoUiPage`：[AutoUiPage 生成器](../docs/zh-CN/source-generators/auto-ui-page-generator.md) +- `AutoRegisterExportedCollections`：[AutoRegisterExportedCollections 生成器](../docs/zh-CN/source-generators/auto-register-exported-collections-generator.md) - Godot 运行时入口：[../GFramework.Godot/README.md](../GFramework.Godot/README.md) -- 集成教程：[docs/zh-CN/tutorials/godot-integration.md](../docs/zh-CN/tutorials/godot-integration.md) +- 集成教程：[Godot 集成教程](../docs/zh-CN/tutorials/godot-integration.md) ## 什么时候不该先看这个包 @@ -202,4 +202,4 @@ public partial class MainMenu : Control - 你只需要 `Game` 契约，不需要 Godot 宿主或生成器： - 先看 `GFramework.Game` 或 `GFramework.Game.Abstractions` - 你在确认项目接线顺序，而不是单个生成器契约： - - 先看 `docs/zh-CN/tutorials/godot-integration.md` + - 先看 [Godot 集成教程](../docs/zh-CN/tutorials/godot-integration.md) diff --git a/GFramework.Godot/README.md b/GFramework.Godot/README.md index eaaf856e..169b6a44 100644 --- a/GFramework.Godot/README.md +++ b/GFramework.Godot/README.md @@ -139,14 +139,14 @@ Godot 上。 ## 文档入口 -- Godot 运行时总览：[docs/zh-CN/godot/index.md](../docs/zh-CN/godot/index.md) -- 架构集成：[docs/zh-CN/godot/architecture.md](../docs/zh-CN/godot/architecture.md) -- 场景系统：[docs/zh-CN/godot/scene.md](../docs/zh-CN/godot/scene.md) -- UI 系统：[docs/zh-CN/godot/ui.md](../docs/zh-CN/godot/ui.md) -- 节点扩展：[docs/zh-CN/godot/extensions.md](../docs/zh-CN/godot/extensions.md) -- 信号系统：[docs/zh-CN/godot/signal.md](../docs/zh-CN/godot/signal.md) -- 日志系统：[docs/zh-CN/godot/logging.md](../docs/zh-CN/godot/logging.md) -- 集成教程：[docs/zh-CN/tutorials/godot-integration.md](../docs/zh-CN/tutorials/godot-integration.md) +- Godot 运行时总览：[Godot 模块总览](../docs/zh-CN/godot/index.md) +- 架构集成：[Godot 架构集成](../docs/zh-CN/godot/architecture.md) +- 场景系统：[Godot 场景系统](../docs/zh-CN/godot/scene.md) +- UI 系统：[Godot UI 系统](../docs/zh-CN/godot/ui.md) +- 节点扩展：[Godot 节点扩展](../docs/zh-CN/godot/extensions.md) +- 信号系统：[Godot 信号系统](../docs/zh-CN/godot/signal.md) +- 日志系统：[Godot 日志系统](../docs/zh-CN/godot/logging.md) +- 集成教程：[Godot 集成教程](../docs/zh-CN/tutorials/godot-integration.md) - 生成器入口：[../GFramework.Godot.SourceGenerators/README.md](../GFramework.Godot.SourceGenerators/README.md) ## 什么时候不该把它当成主入口 diff --git a/README.md b/README.md index 85646537..35db7af5 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,8 @@ ## 从哪里开始 -- 第一次接触框架：[`docs/zh-CN/getting-started/index.md`](docs/zh-CN/getting-started/index.md) -- 想先跑一个最小例子：[`docs/zh-CN/getting-started/quick-start.md`](docs/zh-CN/getting-started/quick-start.md) +- 第一次接触框架：[入门指南](docs/zh-CN/getting-started/index.md) +- 想先跑一个最小例子：[快速开始](docs/zh-CN/getting-started/quick-start.md) - 已经知道要用哪个模块：直接进入对应模块目录下的 `README.md` ## 模块地图 @@ -41,25 +41,25 @@ | --- | --- | --- | | `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [GFramework.Core.SourceGenerators/README.md](GFramework.Core.SourceGenerators/README.md) | | `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [GFramework.Godot.SourceGenerators/README.md](GFramework.Godot.SourceGenerators/README.md) | -| `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [docs/zh-CN/source-generators/index.md](docs/zh-CN/source-generators/index.md) | +| `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [源码生成器总览](docs/zh-CN/source-generators/index.md) | ## 文档导航 仓库根 README 与文档站点保持同一套栏目命名： -- 入门指南：[`docs/zh-CN/getting-started/index.md`](docs/zh-CN/getting-started/index.md) -- Core：[`docs/zh-CN/core/index.md`](docs/zh-CN/core/index.md) -- Game：[`docs/zh-CN/game/index.md`](docs/zh-CN/game/index.md) -- Godot：[`docs/zh-CN/godot/index.md`](docs/zh-CN/godot/index.md) -- 教程：[`docs/zh-CN/tutorials/index.md`](docs/zh-CN/tutorials/index.md) -- 源码生成器：[`docs/zh-CN/source-generators/index.md`](docs/zh-CN/source-generators/index.md) -- ECS：[`docs/zh-CN/ecs/index.md`](docs/zh-CN/ecs/index.md) -- 抽象接口：[`docs/zh-CN/abstractions/index.md`](docs/zh-CN/abstractions/index.md) -- 最佳实践：[`docs/zh-CN/best-practices/index.md`](docs/zh-CN/best-practices/index.md) -- API 参考：[`docs/zh-CN/api-reference/index.md`](docs/zh-CN/api-reference/index.md) -- FAQ：[`docs/zh-CN/faq.md`](docs/zh-CN/faq.md) -- 故障排查：[`docs/zh-CN/troubleshooting.md`](docs/zh-CN/troubleshooting.md) -- 贡献：[`docs/zh-CN/contributing.md`](docs/zh-CN/contributing.md) +- 入门指南：[入门指南](docs/zh-CN/getting-started/index.md) +- Core：[Core](docs/zh-CN/core/index.md) +- Game：[Game](docs/zh-CN/game/index.md) +- Godot：[Godot](docs/zh-CN/godot/index.md) +- 教程：[教程](docs/zh-CN/tutorials/index.md) +- 源码生成器：[源码生成器](docs/zh-CN/source-generators/index.md) +- ECS：[ECS](docs/zh-CN/ecs/index.md) +- 抽象接口：[抽象接口](docs/zh-CN/abstractions/index.md) +- 最佳实践：[最佳实践](docs/zh-CN/best-practices/index.md) +- API 参考：[API 参考](docs/zh-CN/api-reference/index.md) +- FAQ：[常见问题](docs/zh-CN/faq.md) +- 故障排查：[故障排查](docs/zh-CN/troubleshooting.md) +- 贡献：[贡献指南](docs/zh-CN/contributing.md) ## 包选择 @@ -146,7 +146,7 @@ GFramework.sln 提交功能或行为变更时，请把代码、测试和文档一起更新： 1. 先阅读对应模块目录下的 `README.md` -2. 如果改动影响采用路径、安装方式、公共 API 或目录结构，同时更新 `docs/zh-CN/` +2. 如果改动影响采用路径、安装方式、公共 API 或目录结构，同时更新 [中文文档入口](docs/zh-CN/index.md) 3. 对跨模块或多阶段任务，维护 `ai-plan/public/README.md` 与对应主题目录下的 tracking / trace ## 许可证 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 3dbd3f72..f916858e 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,12 +12,12 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-028` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-029` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，本批已收口 `25` 个 `docs/zh-CN` 页面中的站内链接 `.md` / `index.md` 一致性 + - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，本批已收口模块 `README.md`、`docs/index.md` 与多组中文落地页之间的读者入口对齐 - 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明 - - 继续优先处理低风险 metadata 缺口、坏链、README 文档入口对齐与 Markdown 结构问题，避免跨模块语义改写 + - 继续优先处理低风险 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` 在生命周期接法上的一致性 - 保持 active tracking / trace 只承载当前恢复入口，把阶段细节留在 `archive/` @@ -25,7 +25,7 @@ ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 -- `2026-04-24` 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 batch baseline 时，当前分支累计 diff 在 `RP-027` 提交后为 `10` 个文件；本批 write set 额外覆盖 `25` 个 `docs/zh-CN` 页面与 `2` 个 `ai-plan` 入口文件，提交后分支 diff 为 `29 / 75` 个 changed files。 +- `2026-04-24` 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 batch baseline 时，当前分支累计 diff 在 `RP-028` 提交后为 `29` 个文件；本批 write set 额外覆盖 `31` 个文件（`29` 个 README / docs 页面 + `2` 个 `ai-plan` 入口），提交后分支 diff 为 `58 / 75` 个 changed files。 - `2026-04-24` 使用 `$gframework-pr-review` 抓取 PR `#282` 后，确认 latest head commit `982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread；4 条建议均已在本地复核并纳入当前恢复点。 - 本轮 PR follow-up 仅收口仍然成立的 review 项： @@ -34,6 +34,7 @@ - 统一 `docs/zh-CN/troubleshooting.md` 中 `/zh-CN/core/architecture` 与 `/zh-CN/faq` 的 `.md` 链接写法 - 本批次补齐了 `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 指向。 - `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`、 @@ -79,10 +80,12 @@ - 结果：通过；当前 `docs/zh-CN` 站内 Markdown 链接已无缺失扩展名的命中。 - `2026-04-24` `bun run build`（工作目录：`docs/`） - 结果：通过；`25` 个页面的站内链接补齐为显式 `.md` / `index.md` 后站点仍可正常构建，仅保留既有大 chunk warning。 +- `2026-04-24` `bun run build`（工作目录：`docs/`） + - 结果：通过；模块 README、中文落地页 reader-facing 文档入口对齐，以及 `docs/index.md` metadata 调整后站点仍可正常构建，仅保留既有大 chunk warning。 ## 下一步 -1. 若继续执行 `$gframework-batch-boot 75`，优先盘点模块 `README.md`、`docs/index.md` 与文档落地页之间仍未对齐的文档入口、BOM 与旧链接写法。 +1. 当前分支达到 `58 / 75` 个 changed files 后，若继续执行 `$gframework-batch-boot 75`，应优先选择 `5` 到 `10` 个文件以内的小批次，避免显著降低 reviewability。 2. 推送当前批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 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 f82b9464..76ee3b6e 100644 --- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -2,28 +2,25 @@ ## 2026-04-24 -### 当前恢复点：RP-028 +### 当前恢复点：RP-029 -- 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 `$gframework-batch-boot 75` baseline，确认 `RP-027` 提交后的当前分支累计 diff 为 `10` 个文件。 -- 选择“站内 Markdown 链接显式扩展名统一”作为本批次低风险切片，集中处理教程、最佳实践、Core 与 Godot 页面中的目录链接和缺 `.md` 的旧写法。 -- 本批次修改了 `25` 个 `docs/zh-CN` 页面，把 `./`、`../`、`/zh-CN/` 开头的站内 Markdown 链接统一补齐为显式 `.md` 或 `index.md`。 +- 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 `$gframework-batch-boot 75` baseline，确认 `RP-028` 提交后的当前分支累计 diff 为 `29` 个文件。 +- 选择“README 与落地页 reader-facing 文档入口对齐”作为本批次低风险切片，集中处理模块 README、仓库根 README、`docs/index.md` 与多组中文落地页中的裸路径标签和 code span 文档入口。 +- 本批次修改了 `29` 个 README / docs 页面，并补充了 `2` 个 `ai-plan` 入口更新。 -### 当前决策（RP-028） +### 当前决策（RP-029） -- 当 branch diff 仍显著低于 `75` 文件阈值时，继续优先消化低风险链接规范化和 README / landing page 对齐问题，不在同一批次混入高语义重写。 -- 构建失败优先视为机械链接转换回归，先修复批量规则副作用再继续，而不是带着失效链接进入后续批次。 -- active `ai-plan` 入口继续保持轻量，只记录当前恢复点、batch metric、验证结果与下一批候选项。 +- 当 branch diff 接近 `58 / 75` 时，继续批量推进的前提应变成“每批只有很小的 write set 且收益明确”；否则优先停在当前恢复点，保留 reviewability。 +- README 与 landing page 的 reader-facing 入口应优先显示模块名、栏目名或功能名，而不是直接暴露仓库路径。 +- `docs/index.md` 作为语言落地页，即使主要依赖脚本跳转，也应保留明确的 `title` / `description` metadata，避免站点入口缺失基础说明。 -### 当前验证（RP-028） +### 当前验证（RP-029） -- 站内链接巡检： - - `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` 中以 `./`、`../`、`/zh-CN/` 开头且未带扩展名的 Markdown 链接） - - 结果：通过；当前 `docs/zh-CN` 站内 Markdown 链接已无缺失扩展名的命中。 - 站点构建： - `bun run build`（工作目录：`docs/`） - - 结果：通过；统一 `25` 个页面的站内链接后站点仍可正常构建，仅保留既有大 chunk warning。 + - 结果：通过；模块 README、中文落地页 reader-facing 文档入口对齐，以及 `docs/index.md` metadata 调整后站点仍可正常构建，仅保留既有大 chunk warning。 - 当前 stop-condition metric： - - 本批次 write set 为 `27` 个文件（`25` 个文档页面 + `2` 个 `ai-plan` 入口）；本批次提交后分支 diff 为 `29 / 75` 个 changed files。 + - 本批次 write set 为 `31` 个文件（`29` 个 README / docs 页面 + `2` 个 `ai-plan` 入口）；本批次提交后分支 diff 为 `58 / 75` 个 changed files。 ### 归档指针 @@ -35,5 +32,5 @@ ### 下一步 -1. 若继续执行 `$gframework-batch-boot 75`，优先盘点模块 `README.md`、`docs/index.md` 与文档落地页之间仍未对齐的文档入口、BOM 与旧链接写法。 +1. 若继续执行 `$gframework-batch-boot 75`，优先选择 `5` 到 `10` 个文件以内的小批次，例如剩余零散的 README 路径引用或单页 reader-facing 标签修正。 2. 推送本批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。 diff --git a/docs/index.md b/docs/index.md index 8b0c7e99..631b30d7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,7 @@ ---- +--- layout: page +title: Language Selection +description: Redirects visitors to the current Chinese documentation entry and keeps the language landing page discoverable. ---