gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-11 20:38:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
gewuyou 2026-04-23 23:03:40 +08:00 committed by GitHub
commit 2de57f5fde
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
24 changed files with 172 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
.agents/skills/README.md
View File

@ -46,9 +46,22 @@
/gframework-batch-boot <task-or-stop-condition> /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 ```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 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 /gframework-batch-boot keep refactoring repetitive source-generator tests in bounded batches
``` ```

41
.agents/skills/gframework-batch-boot/SKILL.md
View File

@ -50,6 +50,19 @@ For changed-file limits, measure branch-wide scope against the chosen baseline,
- use `git diff --name-only <baseline>...HEAD` - use `git diff --name-only <baseline>...HEAD`
- do not confuse branch diff size with `git status --short` - 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 ## Stop Conditions
Choose one primary stop condition before the first batch and restate it to the user. 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. 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 ## Batch Loop
1. Inspect the current state before the first batch: 1. Inspect the current state before the first batch:
@ -134,6 +173,8 @@ When stopping, report:
## Example Triggers ## 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 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 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.` - `Use $gframework-batch-boot and refresh module docs in waves without asking me to trigger every round.`

42
ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md
View File

@ -12,9 +12,11 @@
## 当前恢复点 ## 当前恢复点
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-019` - 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-023`
- 当前阶段：`Phase 5 - Governance Maintenance` - 当前阶段：`Phase 5 - Governance Maintenance`
- 当前焦点： - 当前焦点：
- 保持 landing page / API 导航页中的仓库 README 入口可点击，避免读者在 docs 站点里遇到裸路径文本
- 继续按 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险导航 / 渲染热点
- 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述 - 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述
- 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性 - 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性
- 保持 active tracking / trace 只承载当前恢复入口，把阶段细节留在 `archive/` - 保持 active tracking / trace 只承载当前恢复入口，把阶段细节留在 `archive/`
@ -36,6 +38,26 @@
`SettingsModel&lt;ISettingsDataRepository&gt;`。 `SettingsModel&lt;ISettingsDataRepository&gt;`。
- 结合当前 PR 已改动的 `docs/zh-CN/godot/storage.md` 做同类巡检后，确认 `SaveRepository&lt;TSaveData&gt;` - 结合当前 PR 已改动的 `docs/zh-CN/godot/storage.md` 做同类巡检后，确认 `SaveRepository&lt;TSaveData&gt;`
也会在 VitePress code span 中按字面量渲染；两处现已在本地统一改为真实泛型写法。 也会在 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 元数据，不是本地 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地
文件缺陷。 文件缺陷。
@ -62,14 +84,24 @@
`docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。 `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` - `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` 两处同类写法，均已修正。 - 结果：命中 `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/`） - `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 泛型写法修正， 1. 若继续执行文档治理批处理，优先改做标题锚点、站内链接和少量非导航型裸路径引用的逐页复核，而不是继续按统一模板机械替换。
然后重新抓取 PR `#272` 确认 Greptile open thread 是否已在新 head commit 上消失。 2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖
2. 如果 PR `#272` 的 `Title check` 仍需要消除，到 GitHub 上把标题改成更具体的文档治理描述。 常见分支阈值场景。
3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、 4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、

67
ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md
View File

@ -2,49 +2,48 @@
## 2026-04-23 ## 2026-04-23
### 当前恢复点：RP-019 ### 当前恢复点：RP-023
- 使用 `$gframework-pr-review` 重新复核当前分支 PR `#272`。 - 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。
- GitHub latest-head review 当前暴露 1 条新的 Greptile open thread： - 本轮目标定义为“继续沿用上一批的 GitHub 外链策略，收口专题页里的裸路径 README 入口”。
`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;` 的同型问题。
- 本轮执行的修复： - 本轮执行的修复：
- 将 `docs/zh-CN/godot/setting.md` 的 `SettingsModel&lt;ISettingsDataRepository&gt;` 改为 - 将 `docs/zh-CN/core/cqrs.md` 与 `ecs/arch.md` 的仓库 README 入口改为 GitHub `main` blob 外链
`SettingsModel<ISettingsDataRepository>` - 将 `docs/zh-CN/abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 的回跳 README 入口改为可点击链接
- 将 `docs/zh-CN/godot/storage.md` 的 `SaveRepository&lt;TSaveData&gt;` 改为 - 将 `docs/zh-CN/source-generators/priority-generator.md`、`context-aware-generator.md`、
`SaveRepository<TSaveData>` `bind-node-signal-generator.md`、`godot-project-generator.md`、`get-node-generator.md`、
- 同步更新 active tracking / trace，记录该 PR review follow-up 与新的恢复点 `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”，也必须按新抓取结果回写。 - 继续使用 `origin/main` 作为 `$gframework-batch-boot 75` 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。
- 对 Markdown inline code 中的 C# 泛型示例，必须直接写真实的 `<T>` 语法，不能在反引号内部再写 - 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。
`&lt;` / `&gt;`，否则 VitePress 会把 entity 当作字面量展示。 - 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。
- 当 latest-head review 命中某个文档表述问题时，应顺手扫描同一批 PR 已改动文档中的同类模式，避免只消掉单条 thread 却把相同渲染缺陷留在相邻页面。 - 当 docs 页需要跳转到 `docs/` 外部的 README 时，使用 GitHub `main` 分支 blob 外链，而不是跨出 `docs/` 根目录的相对路径。
- 当前本地修复完成后，下一次 GitHub 侧复核需要基于新提交/新 head commit，而不是旧的 PR review 快照。 - 第二批继续沿用同一外链策略，避免在同一 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` - `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
- 结果：通过；PR `#272` 处于 `OPEN`，latest head commit 存在 1 条 Greptile open thread，定位到 - 结果：命中 landing / API 导航页中的裸路径仓库入口，已按本轮批次收口 7 个页面。
`docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。 - 第二批专题页巡检：
- 同类模式巡检： - `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
- `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` - 结果：命中 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、`game/scene.md`、
- 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。 `game/ui.md` 与 6 个 `source-generators/*.md` 专题页，均已修复。
- 构建校验： - 构建校验：
- `bun run build`（工作目录：`docs/`） - `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`。 - 为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 `.agents/skills/README.md` 补齐数字速记 stop condition 语义。
- latest-head review 命中 `GFramework.Godot.SourceGenerators/README.md:135` 的错误命名空间引用，并已在本地修正。 - 明确 `$gframework-batch-boot 75` / `75 2000` 默认绑定 `origin/main` 累计 diff 口径。
- README 校验与 `docs/` 站点构建通过，待新提交推送后回 GitHub 侧确认 open thread 消失。 - 完成第一批 landing / API 导航页 README 外链治理，并通过 `docs/` 站点构建。
### 归档指针 ### 归档指针
@ -55,4 +54,4 @@
### 下一步 ### 下一步
1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。 1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。
2. 如果 PR `#272` 的 `Title check` 仍需要处理，到 GitHub 上把标题改成更具体的文档治理描述。 2. 若继续执行文档治理批处理，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接热点，而不是扩成跨模块大波次。

4
docs/zh-CN/abstractions/core-abstractions.md
View File

@ -99,6 +99,6 @@ public sealed class DiagnosticsFeature
1. 先读本页，确认你是否真的只需要契约层 1. 先读本页，确认你是否真的只需要契约层
2. 再看 [`../core/index.md`](../core/index.md) 了解默认运行时怎么组织这些契约 2. 再看 [`../core/index.md`](../core/index.md) 了解默认运行时怎么组织这些契约
3. 回到模块 README： 3. 回到模块 README：
- `GFramework.Core.Abstractions/README.md` - [`GFramework.Core.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
- `GFramework.Core/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) 4. 需要统一导航时，再看 [`../api-reference/index.md`](../api-reference/index.md)

4
docs/zh-CN/abstractions/ecs-arch-abstractions.md
View File

@ -90,5 +90,5 @@ var options = new ArchOptions
1. 先读本页，确认你是否真的只需要契约层 1. 先读本页，确认你是否真的只需要契约层
2. 如果需要默认实现，再看 [`../ecs/arch.md`](../ecs/arch.md) 2. 如果需要默认实现，再看 [`../ecs/arch.md`](../ecs/arch.md)
3. 回到对应模块 README： 3. 回到对应模块 README：
- `GFramework.Ecs.Arch.Abstractions/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` - [`GFramework.Ecs.Arch/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)

4
docs/zh-CN/abstractions/game-abstractions.md
View File

@ -118,5 +118,5 @@ public sealed class ContinueGameCommandHandler
- [`../game/scene.md`](../game/scene.md) - [`../game/scene.md`](../game/scene.md)
- [`../game/ui.md`](../game/ui.md) - [`../game/ui.md`](../game/ui.md)
4. 需要仓库侧入口时，回到： 4. 需要仓库侧入口时，回到：
- `GFramework.Game.Abstractions/README.md` - [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
- `GFramework.Game/README.md` - [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)

12
docs/zh-CN/api-reference/index.md
View File

@ -21,7 +21,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
先读模块 README，再读对应 landing page： 先读模块 README，再读对应 landing page：
- 入门入口：[`../getting-started/index.md`](../getting-started/index.md) - 入门入口：[`../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 文档关注点 | | 模块族 | 模块 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) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 | | `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`、`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 | | `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`、`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、存储、序列化契约 | | `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`、`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 生成器入口 | | `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`、`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 模块契约、系统适配、配置对象和运行时装配边界 | | `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，还是先看教程 ## 先看 XML，还是先看教程

2
docs/zh-CN/core/cqrs.md
View File

@ -186,4 +186,4 @@ RegisterCqrsPipelineBehavior<LoggingBehavior<,>>();
- 架构入口：[architecture](./architecture.md) - 架构入口：[architecture](./architecture.md)
- 上下文入口：[context](./context.md) - 上下文入口：[context](./context.md)
- 生成器专题：[../source-generators/cqrs-handler-registry-generator.md](../source-generators/cqrs-handler-registry-generator.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)

14
docs/zh-CN/core/functional.md
View File

@ -17,7 +17,7 @@ GFramework.Core 提供了一套完整的函数式编程工具，帮助开发者
### Option 类型 ### Option 类型
`Option&lt;T&gt;` 表示可能存在或不存在的值，用于替代 null 引用。它有两种状态： `Option<T>` 表示可能存在或不存在的值，用于替代 null 引用。它有两种状态：
- **Some**：包含一个值 - **Some**：包含一个值
- **None**：不包含值 - **None**：不包含值
@ -26,7 +26,7 @@ GFramework.Core 提供了一套完整的函数式编程工具，帮助开发者
### Result 类型 ### Result 类型
`Result&lt;T&gt;` 表示操作的结果，可能是成功值或失败异常。它有三种状态： `Result<T>` 表示操作的结果，可能是成功值或失败异常。它有三种状态：
- **Success**：操作成功，包含返回值 - **Success**：操作成功，包含返回值
- **Faulted**：操作失败，包含异常信息 - **Faulted**：操作失败，包含异常信息
@ -586,14 +586,14 @@ public async Task<Result<Response>> ProcessRequestAsync(Request request)
### Option vs Nullable ### Option vs Nullable
**Q: Option 和 Nullable&lt;T&gt; 有什么区别？** **Q: Option 和 `Nullable<T>` 有什么区别？**
A: A:
- `Nullable&lt;T&gt;` 只能用于值类型，`Option&lt;T&gt;` 可用于任何类型 - `Nullable<T>` 只能用于值类型，`Option<T>` 可用于任何类型
- `Option&lt;T&gt;` 提供丰富的函数式操作（Map、Bind、Filter 等） - `Option<T>` 提供丰富的函数式操作（Map、Bind、Filter 等）
- `Option&lt;T&gt;` 强制显式处理"无值"情况，更安全 - `Option<T>` 强制显式处理"无值"情况，更安全
- `Option&lt;T&gt;` 可以与 Result 等其他函数式类型组合 - `Option<T>` 可以与 Result 等其他函数式类型组合
### Result vs Exception ### Result vs Exception

10
docs/zh-CN/core/index.md
View File

@ -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. 再看本栏目对应专题页，确认采用顺序、生命周期与推荐接线方式 2. 再看本栏目对应专题页，确认采用顺序、生命周期与推荐接线方式
3. 最后回到源码中的 XML 文档，重点核对这些类型族： 3. 最后回到源码中的 XML 文档，重点核对这些类型族：
- `Architecture` / `IArchitectureContext` - `Architecture` / `IArchitectureContext`
@ -149,7 +149,7 @@ public sealed class CounterArchitecture : Architecture
## 对应模块入口 ## 对应模块入口
- `GFramework.Core/README.md` - [`GFramework.Core/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
- `GFramework.Core.Abstractions/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` - [`docs/zh-CN/api-reference/index.md`](../api-reference/index.md)
- 仓库根 `README.md` - 仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)

2
docs/zh-CN/ecs/arch.md
View File

@ -140,5 +140,5 @@ ecsModule.Update(deltaTime);
- ECS 模块总览：[`index.md`](./index.md) - ECS 模块总览：[`index.md`](./index.md)
- 抽象契约页：[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.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) - 统一 API / XML 导航：[`../api-reference/index.md`](../api-reference/index.md)

6
docs/zh-CN/game/index.md
View File

@ -127,6 +127,6 @@ IStorage storage = new FileStorage("GameData", serializer);
## 对应模块入口 ## 对应模块入口
- `GFramework.Game/README.md` - [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
- `GFramework.Game.Abstractions/README.md` - [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
- 仓库根 `README.md` - 仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)

4
docs/zh-CN/game/scene.md
View File

@ -258,5 +258,5 @@ await sceneRouter.PopAsync();
1. [game/index.md](./index.md) 1. [game/index.md](./index.md)
2. [ui.md](./ui.md) 2. [ui.md](./ui.md)
3. `GFramework.Game/README.md` 3. [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
4. `GFramework.Game.Abstractions/README.md` 4. [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)

4
docs/zh-CN/game/ui.md
View File

@ -329,5 +329,5 @@ uiRouter.Hide(modalHandle, UiLayer.Modal);
1. [game/index.md](./index.md) 1. [game/index.md](./index.md)
2. [scene.md](./scene.md) 2. [scene.md](./scene.md)
3. [../source-generators/auto-ui-page-generator.md](../source-generators/auto-ui-page-generator.md) 3. [../source-generators/auto-ui-page-generator.md](../source-generators/auto-ui-page-generator.md)
4. `GFramework.Game/README.md` 4. [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
5. `GFramework.Game.Abstractions/README.md` 5. [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)

6
docs/zh-CN/getting-started/index.md
View File

@ -46,7 +46,7 @@
对应文档： 对应文档：
- [`../core/cqrs.md`](../core/cqrs.md) - [`../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) - [`../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 ### 想接入 Godot
@ -76,7 +76,7 @@
对应文档： 对应文档：
- [`../godot/index.md`](../godot/index.md) - [`../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 什么时候装 ## Source Generators 什么时候装

2
docs/zh-CN/source-generators/auto-register-exported-collections-generator.md
View File

@ -220,4 +220,4 @@ public List<IntConfig>? Values { get; } = new();
1. [/zh-CN/source-generators/index](./index.md) 1. [/zh-CN/source-generators/index](./index.md)
2. [/zh-CN/game/config-system](../game/config-system.md) 2. [/zh-CN/game/config-system](../game/config-system.md)
3. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.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)

2
docs/zh-CN/source-generators/bind-node-signal-generator.md
View File

@ -189,4 +189,4 @@ private void OnAnyButtonPressed()
1. [/zh-CN/source-generators/get-node-generator](./get-node-generator.md) 1. [/zh-CN/source-generators/get-node-generator](./get-node-generator.md)
2. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.md) 2. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.md)
3. [/zh-CN/godot/ui](../godot/ui.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)

2
docs/zh-CN/source-generators/context-aware-generator.md
View File

@ -195,4 +195,4 @@ finally
1. [context-get-generator.md](./context-get-generator.md) 1. [context-get-generator.md](./context-get-generator.md)
2. [logging-generator.md](./logging-generator.md) 2. [logging-generator.md](./logging-generator.md)
3. [../core/index.md](../core/index.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)

2
docs/zh-CN/source-generators/get-node-generator.md
View File

@ -195,4 +195,4 @@ public override void _Ready()
1. [/zh-CN/source-generators/bind-node-signal-generator](./bind-node-signal-generator.md) 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) 2. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.md)
3. [/zh-CN/godot/ui](../godot/ui.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)

2
docs/zh-CN/source-generators/godot-project-generator.md
View File

@ -217,4 +217,4 @@ AutoLoad 名称也遵循同样的冲突处理策略。
1. [/zh-CN/source-generators/get-node-generator](./get-node-generator.md) 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) 2. [/zh-CN/source-generators/bind-node-signal-generator](./bind-node-signal-generator.md)
3. [/zh-CN/tutorials/godot-integration](../tutorials/godot-integration.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)

8
docs/zh-CN/source-generators/index.md
View File

@ -101,7 +101,7 @@ GFramework 当前发布的生成器包是：
## 对应模块入口 ## 对应模块入口
- `GFramework.Core.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` - [`GFramework.Game.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md)
- `GFramework.Cqrs.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` - [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)

2
docs/zh-CN/source-generators/priority-generator.md
View File

@ -213,4 +213,4 @@ public sealed class DynamicPrioritySystem : IPrioritized
1. [context-aware-generator.md](./context-aware-generator.md) 1. [context-aware-generator.md](./context-aware-generator.md)
2. [context-get-generator.md](./context-get-generator.md) 2. [context-get-generator.md](./context-get-generator.md)
3. [../core/index.md](../core/index.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)

4
docs/zh-CN/tutorials/functional-programming.md
View File

@ -121,7 +121,7 @@ namespace MyGame.Services
**代码说明**： **代码说明**：
- `Option&lt;T&gt;` 明确表示值可能不存在，避免 NullReferenceException - `Option<T>` 明确表示值可能不存在，避免 NullReferenceException
- `Match` 强制处理两种情况，不会遗漏 null 检查 - `Match` 强制处理两种情况，不会遗漏 null 检查
- `Map` 和 `Bind` 实现链式转换，代码更简洁 - `Map` 和 `Bind` 实现链式转换，代码更简洁
- `Filter` 可以安全地过滤值 - `Filter` 可以安全地过滤值
@ -250,7 +250,7 @@ namespace MyGame.Services
**代码说明**： **代码说明**：
- `Result&lt;T&gt;` 将错误作为值返回，而不是抛出异常 - `Result<T>` 将错误作为值返回，而不是抛出异常
- `Result.Try` 自动捕获异常并转换为 Result - `Result.Try` 自动捕获异常并转换为 Result
- `Bind` 可以链接多个可能失败的操作 - `Bind` 可以链接多个可能失败的操作
- `Match` 强制处理成功和失败两种情况 - `Match` 强制处理成功和失败两种情况