Merge pull request #281 from GeWuYou/docs/sdk-update-documentation

2026-05-07 08:44:29 +08:00 · 2026-04-23 23:03:40 +08:00 · 2026-04-23 23:03:40 +08:00 · 2de57f5fde
commit 2de57f5fde
parent fdccfc4448 a3501c9b91
24 changed files with 172 additions and 87 deletions
--- a/.agents/skills/README.md
+++ b/.agents/skills/README.md
@ -46,9 +46,22 @@
 /gframework-batch-boot <task-or-stop-condition>
 ```

+批处理阈值速记：
+
+```bash
+/gframework-batch-boot 75
+/gframework-batch-boot 75 2000
+```
+
+- 单个数字默认表示“当前分支全部提交相对远程 `origin/main` 接近多少个文件变更时停止”
+- 两个数字默认表示“当前分支全部提交相对远程 `origin/main` 的 `文件数 OR 变更行数`”，顺序固定为 `<files> <lines>`
+- 不推荐写 `/gframework-batch-boot 75 | 2000`，因为 `|` 很像 shell pipe；若用户这样写，也应按 OR 语义理解并在后续说明中归一化成无 `|` 版本
+
 示例：

 ```bash
+/gframework-batch-boot 75
+/gframework-batch-boot 75 2000
 /gframework-batch-boot continue analyzer warning reduction until branch diff vs origin/main approaches 75 files
 /gframework-batch-boot keep refactoring repetitive source-generator tests in bounded batches
 ```
--- a/.agents/skills/gframework-batch-boot/SKILL.md
+++ b/.agents/skills/gframework-batch-boot/SKILL.md
@ -50,6 +50,19 @@ For changed-file limits, measure branch-wide scope against the chosen baseline,
 - use `git diff --name-only <baseline>...HEAD`
 - do not confuse branch diff size with `git status --short`

+For changed-line limits, also measure branch-wide scope against the chosen baseline:
+
+- prefer `git diff --numstat <baseline>...HEAD`
+- treat "changed lines" as `added + deleted` summed across the branch diff
+- do not use working-tree-only line counts as a substitute for branch-wide scope
+
+For shorthand numeric thresholds, use a fixed default baseline:
+
+- compare the current branch's cumulative diff against remote `origin/main`
+- include all commits reachable from `HEAD` that are not already in `origin/main`
+- do not reinterpret shorthand thresholds as "this batch only" or "current unstaged changes only"
+- only use another baseline when the user explicitly names it in the prompt
+
 ## Stop Conditions

 Choose one primary stop condition before the first batch and restate it to the user.
@ -63,6 +76,32 @@ Common stop conditions:

 If multiple stop conditions exist, rank them and treat one as primary.

+## Shorthand Stop-Condition Syntax
+
+`gframework-batch-boot` may be invoked with shorthand numeric thresholds when the user clearly wants a branch-size stop
+condition instead of a long natural-language prompt.
+
+Interpret shorthand as follows:
+
+- `$gframework-batch-boot 75`
+  - means: stop when the current branch's cumulative diff vs remote `origin/main` approaches `75` changed files
+- `$gframework-batch-boot 75 2000`
+  - means: stop when the current branch's cumulative diff vs remote `origin/main` approaches `75` changed files OR
+    `2000` changed lines
+  - default positional meaning is `<files> <lines>`
+- `$gframework-batch-boot 75 | 2000`
+  - may be interpreted as the same OR shorthand in plain-language chat
+  - when restating, planning, or documenting the command, normalize it to `$gframework-batch-boot 75 2000`
+  - prefer the no-pipe form because `|` is easy to confuse with a shell pipeline
+
+When shorthand is used:
+
+- report the resolved thresholds explicitly before the first batch
+- report that the baseline is remote `origin/main`, unless the user explicitly overrides it
+- if two numeric thresholds are present, treat file count as the default primary metric for status reporting unless the
+  user says otherwise
+- stop when either threshold is reached or exceeded, even if the other threshold still has headroom
+
 ## Batch Loop

 1. Inspect the current state before the first batch:
@ -134,6 +173,8 @@ When stopping, report:

 ## Example Triggers

+- `Use $gframework-batch-boot 75 to keep reducing analyzer warnings until the branch diff vs baseline approaches 75 files.`
+- `Use $gframework-batch-boot 75 2000 to keep reducing warnings until the branch diff approaches 75 files or 2000 changed lines.`
 - `Use $gframework-batch-boot and keep reducing analyzer warnings until the branch diff vs origin/main approaches 75 files.`
 - `Use $gframework-batch-boot to continue this repetitive test refactor in bounded batches until the warning count drops below 10.`
 - `Use $gframework-batch-boot and refresh module docs in waves without asking me to trigger every round.`
--- 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,9 +12,11 @@

 ## 当前恢复点

- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-019`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-023`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
+  - 保持 landing page / API 导航页中的仓库 README 入口可点击，避免读者在 docs 站点里遇到裸路径文本
+  - 继续按 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险导航 / 渲染热点
  - 保持 `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/`
@ -36,6 +38,26 @@
  `SettingsModel&lt;ISettingsDataRepository&gt;`。
 - 结合当前 PR 已改动的 `docs/zh-CN/godot/storage.md` 做同类巡检后，确认 `SaveRepository&lt;TSaveData&gt;`
  也会在 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&lt;T&gt;`、`Result&lt;T&gt;`、`Nullable&lt;T&gt;` 已统一改为真实
+  泛型写法，避免在 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 元数据，不是本地
  文件缺陷。

@ -62,14 +84,24 @@
    `docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。
 - `2026-04-23` `rg -n '`[^`]*&lt;[^`]*`|`[^`]*&gt;[^`]*`' 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 '`[^`]*&lt;[^`]*`|`[^`]*&gt;[^`]*`' 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/`）
-  - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
+  - 结果：通过；仓库 README 外链改为 GitHub `main` blob 后，不再触发 VitePress dead link；仅保留既有大 chunk warning。

 ## 下一步

-1. 提交并推送本地对 `docs/zh-CN/godot/setting.md` 与 `docs/zh-CN/godot/storage.md` 的 Markdown 泛型写法修正，
-   然后重新抓取 PR `#272` 确认 Greptile open thread 是否已在新 head commit 上消失。
-2. 如果 PR `#272` 的 `Title check` 仍需要消除，到 GitHub 上把标题改成更具体的文档治理描述。
+1. 若继续执行文档治理批处理，优先改做标题锚点、站内链接和少量非导航型裸路径引用的逐页复核，而不是继续按统一模板机械替换。
+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`、
--- 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,49 +2,48 @@

 ## 2026-04-23

-### 当前恢复点：RP-019
+### 当前恢复点：RP-023

- 使用 `$gframework-pr-review` 重新复核当前分支 PR `#272`。
- GitHub latest-head review 当前暴露 1 条新的 Greptile open thread：
-  `docs/zh-CN/godot/setting.md:75` 在 inline code 中写成
-  `SettingsModel&lt;ISettingsDataRepository&gt;`。
- 本地核对当前文档渲染语义后，确认 CommonMark / VitePress 不会在 code span 内解码 HTML entity，
-  该评论成立。
- 对当前 PR 已变更的 Godot 文档做同类扫描后，又在 `docs/zh-CN/godot/storage.md:102` 发现
-  `SaveRepository&lt;TSaveData&gt;` 的同型问题。
+- 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。
+- 本轮目标定义为“继续沿用上一批的 GitHub 外链策略，收口专题页里的裸路径 README 入口”。
 - 本轮执行的修复：
-  - 将 `docs/zh-CN/godot/setting.md` 的 `SettingsModel&lt;ISettingsDataRepository&gt;` 改为
-    `SettingsModel<ISettingsDataRepository>`
-  - 将 `docs/zh-CN/godot/storage.md` 的 `SaveRepository&lt;TSaveData&gt;` 改为
-    `SaveRepository<TSaveData>`
-  - 同步更新 active tracking / trace，记录该 PR review follow-up 与新的恢复点
+  - 将 `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-019）
+### 当前决策（RP-023）

- PR review 结果以 GitHub latest-head open threads 为准；即便 active tracking 曾记录“无 open thread”，也必须按新抓取结果回写。
- 对 Markdown inline code 中的 C# 泛型示例，必须直接写真实的 `<T>` 语法，不能在反引号内部再写
-  `&lt;` / `&gt;`，否则 VitePress 会把 entity 当作字面量展示。
- 当 latest-head review 命中某个文档表述问题时，应顺手扫描同一批 PR 已改动文档中的同类模式，避免只消掉单条 thread 却把相同渲染缺陷留在相邻页面。
- 当前本地修复完成后，下一次 GitHub 侧复核需要基于新提交/新 head commit，而不是旧的 PR review 快照。
+- 继续使用 `origin/main` 作为 `$gframework-batch-boot 75` 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。
+- 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。
+- 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。
+- 当 docs 页需要跳转到 `docs/` 外部的 README 时，使用 GitHub `main` 分支 blob 外链，而不是跨出 `docs/` 根目录的相对路径。
+- 第二批继续沿用同一外链策略，避免在同一 docs surface 中混用“裸路径 / 相对死链 / GitHub 外链”三套入口风格。

-### 当前验证（RP-019）
+### 当前验证（RP-023）

- PR review 抓取：
-  - `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 渲染问题。
- 同类模式巡检：
-  - `rg -n '`[^`]*&lt;[^`]*`|`[^`]*&gt;[^`]*`' 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` 两处同类写法，均已修正。
+- 导航热点巡检：
+  - `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/`）
-  - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
+  - 结果：通过；将仓库 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-018）
+### 归档摘要（RP-022）

- 使用 `$gframework-pr-review` 重新复核当前分支 PR `#272`。
- latest-head review 命中 `GFramework.Godot.SourceGenerators/README.md:135` 的错误命名空间引用，并已在本地修正。
- README 校验与 `docs/` 站点构建通过，待新提交推送后回 GitHub 侧确认 open thread 消失。
+- 为 `.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/` 站点构建。

 ### 归档指针

@ -55,4 +54,4 @@
 ### 下一步

 1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。
-2. 如果 PR `#272` 的 `Title check` 仍需要处理，到 GitHub 上把标题改成更具体的文档治理描述。
+2. 若继续执行文档治理批处理，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接热点，而不是扩成跨模块大波次。
--- a/docs/zh-CN/abstractions/core-abstractions.md
+++ b/docs/zh-CN/abstractions/core-abstractions.md
@ -99,6 +99,6 @@ public sealed class DiagnosticsFeature
 1. 先读本页，确认你是否真的只需要契约层
 2. 再看 [`../core/index.md`](../core/index.md) 了解默认运行时怎么组织这些契约
 3. 回到模块 README：
-   - `GFramework.Core.Abstractions/README.md`
-   - `GFramework.Core/README.md`
+   - [`GFramework.Core.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
+   - [`GFramework.Core/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
 4. 需要统一导航时，再看 [`../api-reference/index.md`](../api-reference/index.md)
--- a/docs/zh-CN/abstractions/ecs-arch-abstractions.md
+++ b/docs/zh-CN/abstractions/ecs-arch-abstractions.md
@ -90,5 +90,5 @@ var options = new ArchOptions
 1. 先读本页，确认你是否真的只需要契约层
 2. 如果需要默认实现，再看 [`../ecs/arch.md`](../ecs/arch.md)
 3. 回到对应模块 README：
-   - `GFramework.Ecs.Arch.Abstractions/README.md`
-   - `GFramework.Ecs.Arch/README.md`
+   - [`GFramework.Ecs.Arch.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch.Abstractions/README.md)
+   - [`GFramework.Ecs.Arch/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
--- a/docs/zh-CN/abstractions/game-abstractions.md
+++ b/docs/zh-CN/abstractions/game-abstractions.md
@ -118,5 +118,5 @@ public sealed class ContinueGameCommandHandler
   - [`../game/scene.md`](../game/scene.md)
   - [`../game/ui.md`](../game/ui.md)
 4. 需要仓库侧入口时，回到：
-   - `GFramework.Game.Abstractions/README.md`
-   - `GFramework.Game/README.md`
+   - [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
+   - [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@ -21,7 +21,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
 先读模块 README，再读对应 landing page：

 - 入门入口：[`../getting-started/index.md`](../getting-started/index.md)
- 根模块地图：仓库根 `README.md`
+- 根模块地图：仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)

 ### 想确认“这个功能属于哪个模块”

@ -29,11 +29,11 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题

 | 模块族 | 模块 README | 站内入口 | XML 文档关注点 |
 | --- | --- | --- | --- |
-| `Core` / `Core.Abstractions` | `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` | [`../core/index.md`](../core/index.md)、[`../abstractions/core-abstractions.md`](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
-| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md` | [`../core/cqrs.md`](../core/cqrs.md)、[`../source-generators/cqrs-handler-registry-generator.md`](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback contract |
-| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md` | [`../game/index.md`](../game/index.md)、[`../abstractions/game-abstractions.md`](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
-| `Godot` / `Godot.SourceGenerators` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md` | [`../godot/index.md`](../godot/index.md)、[`../source-generators/godot-project-generator.md`](../source-generators/godot-project-generator.md)、[`../source-generators/get-node-generator.md`](../source-generators/get-node-generator.md)、[`../source-generators/bind-node-signal-generator.md`](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
-| `Ecs.Arch` / `Ecs.Arch.Abstractions` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md` | [`../ecs/index.md`](../ecs/index.md)、[`../ecs/arch.md`](../ecs/arch.md)、[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |
+| `Core` / `Core.Abstractions` | [`GFramework.Core/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)、[`GFramework.Core.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md) | [`../core/index.md`](../core/index.md)、[`../abstractions/core-abstractions.md`](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
+| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [`GFramework.Cqrs/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)、[`GFramework.Cqrs.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.Abstractions/README.md)、[`GFramework.Cqrs.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.SourceGenerators/README.md) | [`../core/cqrs.md`](../core/cqrs.md)、[`../source-generators/cqrs-handler-registry-generator.md`](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback contract |
+| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)、[`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)、[`GFramework.Game.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md) | [`../game/index.md`](../game/index.md)、[`../abstractions/game-abstractions.md`](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
+| `Godot` / `Godot.SourceGenerators` | [`GFramework.Godot/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)、[`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) | [`../godot/index.md`](../godot/index.md)、[`../source-generators/godot-project-generator.md`](../source-generators/godot-project-generator.md)、[`../source-generators/get-node-generator.md`](../source-generators/get-node-generator.md)、[`../source-generators/bind-node-signal-generator.md`](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
+| `Ecs.Arch` / `Ecs.Arch.Abstractions` | [`GFramework.Ecs.Arch/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)、[`GFramework.Ecs.Arch.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch.Abstractions/README.md) | [`../ecs/index.md`](../ecs/index.md)、[`../ecs/arch.md`](../ecs/arch.md)、[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |

 ## 先看 XML，还是先看教程

--- a/docs/zh-CN/core/cqrs.md
+++ b/docs/zh-CN/core/cqrs.md
@ -186,4 +186,4 @@ RegisterCqrsPipelineBehavior<LoggingBehavior<,>>();
 - 架构入口：[architecture](./architecture.md)
 - 上下文入口：[context](./context.md)
 - 生成器专题：[../source-generators/cqrs-handler-registry-generator.md](../source-generators/cqrs-handler-registry-generator.md)
- 模块 README：`GFramework.Cqrs/README.md`
+- 模块 README：[`GFramework.Cqrs/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)
--- a/docs/zh-CN/core/functional.md
+++ b/docs/zh-CN/core/functional.md
@ -17,7 +17,7 @@ GFramework.Core 提供了一套完整的函数式编程工具，帮助开发者

 ### Option 类型

-`Option&lt;T&gt;` 表示可能存在或不存在的值，用于替代 null 引用。它有两种状态：
+`Option<T>` 表示可能存在或不存在的值，用于替代 null 引用。它有两种状态：

 - **Some**：包含一个值
 - **None**：不包含值
@ -26,7 +26,7 @@ GFramework.Core 提供了一套完整的函数式编程工具，帮助开发者

 ### Result 类型

-`Result&lt;T&gt;` 表示操作的结果，可能是成功值或失败异常。它有三种状态：
+`Result<T>` 表示操作的结果，可能是成功值或失败异常。它有三种状态：

 - **Success**：操作成功，包含返回值
 - **Faulted**：操作失败，包含异常信息
@ -586,14 +586,14 @@ public async Task<Result<Response>> ProcessRequestAsync(Request request)

 ### Option vs Nullable

-**Q: Option 和 Nullable&lt;T&gt; 有什么区别？**
+**Q: Option 和 `Nullable<T>` 有什么区别？**

 A:

- `Nullable&lt;T&gt;` 只能用于值类型，`Option&lt;T&gt;` 可用于任何类型
- `Option&lt;T&gt;` 提供丰富的函数式操作（Map、Bind、Filter 等）
- `Option&lt;T&gt;` 强制显式处理"无值"情况，更安全
- `Option&lt;T&gt;` 可以与 Result 等其他函数式类型组合
+- `Nullable<T>` 只能用于值类型，`Option<T>` 可用于任何类型
+- `Option<T>` 提供丰富的函数式操作（Map、Bind、Filter 等）
+- `Option<T>` 强制显式处理"无值"情况，更安全
+- `Option<T>` 可以与 Result 等其他函数式类型组合

 ### Result vs Exception

--- a/docs/zh-CN/core/index.md
+++ b/docs/zh-CN/core/index.md
@ -71,7 +71,7 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions

 如果你已经知道模块归属，但想确认公开类型的契约边界，建议按下面顺序阅读：

-1. 先看模块 README `GFramework.Core/README.md`，确认包关系和目录边界
+1. 先看模块 README [`GFramework.Core/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)，确认包关系和目录边界
 2. 再看本栏目对应专题页，确认采用顺序、生命周期与推荐接线方式
 3. 最后回到源码中的 XML 文档，重点核对这些类型族：
   - `Architecture` / `IArchitectureContext`
@ -149,7 +149,7 @@ public sealed class CounterArchitecture : Architecture

 ## 对应模块入口

- `GFramework.Core/README.md`
- `GFramework.Core.Abstractions/README.md`
- `docs/zh-CN/api-reference/index.md`
- 仓库根 `README.md`
+- [`GFramework.Core/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
+- [`GFramework.Core.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
+- [`docs/zh-CN/api-reference/index.md`](../api-reference/index.md)
+- 仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)
--- a/docs/zh-CN/ecs/arch.md
+++ b/docs/zh-CN/ecs/arch.md
@ -140,5 +140,5 @@ ecsModule.Update(deltaTime);

 - ECS 模块总览：[`index.md`](./index.md)
 - 抽象契约页：[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md)
- 仓库模块 README：`GFramework.Ecs.Arch/README.md`
+- 仓库模块 README：[`GFramework.Ecs.Arch/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
 - 统一 API / XML 导航：[`../api-reference/index.md`](../api-reference/index.md)
--- a/docs/zh-CN/game/index.md
+++ b/docs/zh-CN/game/index.md
@ -127,6 +127,6 @@ IStorage storage = new FileStorage("GameData", serializer);

 ## 对应模块入口

- `GFramework.Game/README.md`
- `GFramework.Game.Abstractions/README.md`
- 仓库根 `README.md`
+- [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
+- [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
+- 仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)
--- a/docs/zh-CN/game/scene.md
+++ b/docs/zh-CN/game/scene.md
@ -258,5 +258,5 @@ await sceneRouter.PopAsync();

 1. [game/index.md](./index.md)
 2. [ui.md](./ui.md)
-3. `GFramework.Game/README.md`
-4. `GFramework.Game.Abstractions/README.md`
+3. [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
+4. [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
--- a/docs/zh-CN/game/ui.md
+++ b/docs/zh-CN/game/ui.md
@ -329,5 +329,5 @@ uiRouter.Hide(modalHandle, UiLayer.Modal);
 1. [game/index.md](./index.md)
 2. [scene.md](./scene.md)
 3. [../source-generators/auto-ui-page-generator.md](../source-generators/auto-ui-page-generator.md)
-4. `GFramework.Game/README.md`
-5. `GFramework.Game.Abstractions/README.md`
+4. [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
+5. [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
--- a/docs/zh-CN/getting-started/index.md
+++ b/docs/zh-CN/getting-started/index.md
@ -46,7 +46,7 @@
 对应文档：

 - [`../core/cqrs.md`](../core/cqrs.md)
- 仓库内模块入口：`GFramework.Cqrs/README.md`
+- 仓库内模块入口：[`GFramework.Cqrs/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)

 ### 想做游戏运行时

@ -65,7 +65,7 @@
 对应文档：

 - [`../game/index.md`](../game/index.md)
- 仓库内模块入口：`GFramework.Game/README.md`
+- 仓库内模块入口：[`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)

 ### 想接入 Godot

@ -76,7 +76,7 @@
 对应文档：

 - [`../godot/index.md`](../godot/index.md)
- 仓库内模块入口：`GFramework.Godot/README.md`
+- 仓库内模块入口：[`GFramework.Godot/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)

 ## Source Generators 什么时候装

--- a/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md
+++ b/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md
@ -220,4 +220,4 @@ public List<IntConfig>? Values { get; } = new();
 1. [/zh-CN/source-generators/index](./index.md)
 2. [/zh-CN/game/config-system](../game/config-system.md)
 3. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.md)
-4. `GFramework.Godot.SourceGenerators/README.md`
+4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/bind-node-signal-generator.md
+++ b/docs/zh-CN/source-generators/bind-node-signal-generator.md
@ -189,4 +189,4 @@ private void OnAnyButtonPressed()
 1. [/zh-CN/source-generators/get-node-generator](./get-node-generator.md)
 2. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.md)
 3. [/zh-CN/godot/ui](../godot/ui.md)
-4. `GFramework.Godot.SourceGenerators/README.md`
+4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/context-aware-generator.md
+++ b/docs/zh-CN/source-generators/context-aware-generator.md
@ -195,4 +195,4 @@ finally
 1. [context-get-generator.md](./context-get-generator.md)
 2. [logging-generator.md](./logging-generator.md)
 3. [../core/index.md](../core/index.md)
-4. `GFramework.Core.SourceGenerators/README.md`
+4. [`GFramework.Core.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/get-node-generator.md
+++ b/docs/zh-CN/source-generators/get-node-generator.md
@ -195,4 +195,4 @@ public override void _Ready()
 1. [/zh-CN/source-generators/bind-node-signal-generator](./bind-node-signal-generator.md)
 2. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.md)
 3. [/zh-CN/godot/ui](../godot/ui.md)
-4. `GFramework.Godot.SourceGenerators/README.md`
+4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/godot-project-generator.md
+++ b/docs/zh-CN/source-generators/godot-project-generator.md
@ -217,4 +217,4 @@ AutoLoad 名称也遵循同样的冲突处理策略。
 1. [/zh-CN/source-generators/get-node-generator](./get-node-generator.md)
 2. [/zh-CN/source-generators/bind-node-signal-generator](./bind-node-signal-generator.md)
 3. [/zh-CN/tutorials/godot-integration](../tutorials/godot-integration.md)
-4. `GFramework.Godot.SourceGenerators/README.md`
+4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/index.md
+++ b/docs/zh-CN/source-generators/index.md
@ -101,7 +101,7 @@ GFramework 当前发布的生成器包是：

 ## 对应模块入口

- `GFramework.Core.SourceGenerators/README.md`
- `GFramework.Game.SourceGenerators/README.md`
- `GFramework.Cqrs.SourceGenerators/README.md`
- `GFramework.Godot.SourceGenerators/README.md`
+- [`GFramework.Core.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
+- [`GFramework.Game.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md)
+- [`GFramework.Cqrs.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.SourceGenerators/README.md)
+- [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/priority-generator.md
+++ b/docs/zh-CN/source-generators/priority-generator.md
@ -213,4 +213,4 @@ public sealed class DynamicPrioritySystem : IPrioritized
 1. [context-aware-generator.md](./context-aware-generator.md)
 2. [context-get-generator.md](./context-get-generator.md)
 3. [../core/index.md](../core/index.md)
-4. `GFramework.Core.SourceGenerators/README.md`
+4. [`GFramework.Core.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
--- a/docs/zh-CN/tutorials/functional-programming.md
+++ b/docs/zh-CN/tutorials/functional-programming.md
@ -121,7 +121,7 @@ namespace MyGame.Services

 **代码说明**：

- `Option&lt;T&gt;` 明确表示值可能不存在，避免 NullReferenceException
+- `Option<T>` 明确表示值可能不存在，避免 NullReferenceException
 - `Match` 强制处理两种情况，不会遗漏 null 检查
 - `Map` 和 `Bind` 实现链式转换，代码更简洁
 - `Filter` 可以安全地过滤值
@ -250,7 +250,7 @@ namespace MyGame.Services

 **代码说明**：

- `Result&lt;T&gt;` 将错误作为值返回，而不是抛出异常
+- `Result<T>` 将错误作为值返回，而不是抛出异常
 - `Result.Try` 自动捕获异常并转换为 Result
 - `Bind` 可以链接多个可能失败的操作
 - `Match` 强制处理成功和失败两种情况