From 59fe63bba67c34fe0851ef0158cf540d8f927833 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 18:06:52 +0800 Subject: [PATCH 1/6] =?UTF-8?q?fix(docs):=20=E4=BF=AE=E6=AD=A3=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E4=B8=AD=E7=9A=84=E6=B3=9B=E5=9E=8B=E5=86=85=E8=81=94?= =?UTF-8?q?=E4=BB=A3=E7=A0=81=E6=B8=B2=E6=9F=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修复 Core 与函数式教程页面中的泛型 inline code 写法，避免 VitePress 将 HTML entity 按字面量展示 - 更新 documentation-full-coverage-governance 的 tracking 与 trace，记录本轮批处理基线、验证和恢复点 --- ...ation-full-coverage-governance-tracking.md | 19 ++++--- ...entation-full-coverage-governance-trace.md | 51 ++++++++----------- docs/zh-CN/core/functional.md | 14 ++--- .../zh-CN/tutorials/functional-programming.md | 4 +- 4 files changed, 43 insertions(+), 45 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 578662a2..5dda9d86 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,9 +12,10 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-019` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-020` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： + - 保持 `Core` functional docs surface 的 inline code / 泛型示例在 VitePress 下按真实 C# 语法渲染 - 保持 `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 +37,11 @@ `SettingsModel<ISettingsDataRepository>`。 - 结合当前 PR 已改动的 `docs/zh-CN/godot/storage.md` 做同类巡检后，确认 `SaveRepository<TSaveData>` 也会在 VitePress code span 中按字面量渲染；两处现已在本地统一改为真实泛型写法。 +- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对 + `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 执行同类模式巡检，确认剩余热点仅位于 + `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处。 +- 上述 8 处 inline code 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 已统一改为真实 + 泛型写法，避免在 VitePress 中显示字面量 HTML entity。 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地 文件缺陷。 @@ -62,15 +68,16 @@ `docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。 - `2026-04-23` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' GFramework.Godot.SourceGenerators/README.md GFramework.Godot/README.md README.md docs/zh-CN/api-reference/index.md docs/zh-CN/game/data.md docs/zh-CN/game/serialization.md docs/zh-CN/game/setting.md docs/zh-CN/game/storage.md docs/zh-CN/godot/setting.md docs/zh-CN/godot/storage.md docs/zh-CN/source-generators/index.md` - 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。 +- `2026-04-23` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'` + - 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。 - `2026-04-23` `bun run build`（工作目录：`docs/`） - 结果：通过；仅保留既有 VitePress 大 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 上把标题改成更具体的文档治理描述。 -3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 +1. 对 `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 继续做下一类低风险 Markdown 渲染巡检，优先排查 code span 内 + 的 HTML entity、站点内链接和标题锚点是否仍与当前页面结构一致。 +2. 若后续分支继续调整 `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`、 +3. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、 `docs/zh-CN/tutorials/godot-integration.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 fb3c5093..5e73a5fd 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,49 +2,40 @@ ## 2026-04-23 -### 当前恢复点：RP-019 +### 当前恢复点：RP-020 -- 使用 `$gframework-pr-review` 重新复核当前分支 PR `#272`。 -- GitHub latest-head review 当前暴露 1 条新的 Greptile open thread： - `docs/zh-CN/godot/setting.md:75` 在 inline code 中写成 - `SettingsModel<ISettingsDataRepository>`。 -- 本地核对当前文档渲染语义后，确认 CommonMark / VitePress 不会在 code span 内解码 HTML entity， - 该评论成立。 -- 对当前 PR 已变更的 Godot 文档做同类扫描后，又在 `docs/zh-CN/godot/storage.md:102` 发现 - `SaveRepository<TSaveData>` 的同型问题。 +- 按 `$gframework-batch-boot` 继续执行 `documentation-full-coverage-governance`。 +- 将这轮批处理目标定义为“清理 README / `docs/zh-CN` / 模块 README 中仍会在 inline code 里被字面渲染的 HTML 泛型实体”。 +- 基线选择为 `origin/main` `aa879d2`（`2026-04-23T17:51:41+08:00`）；当前分支 `docs/sdk-update-documentation` + 与该基线零差异，适合继续做小批次文档治理。 +- 以 `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'` 扫描后，确认剩余热点只在 + `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md`，共 8 处。 - 本轮执行的修复： - - 将 `docs/zh-CN/godot/setting.md` 的 `SettingsModel<ISettingsDataRepository>` 改为 - `SettingsModel` - - 将 `docs/zh-CN/godot/storage.md` 的 `SaveRepository<TSaveData>` 改为 - `SaveRepository` - - 同步更新 active tracking / trace，记录该 PR review follow-up 与新的恢复点 + - 将 `docs/zh-CN/core/functional.md` 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 改为真实泛型写法 + - 将 `docs/zh-CN/tutorials/functional-programming.md` 中的 `Option<T>`、`Result<T>` 改为真实泛型写法 + - 同步更新 active tracking / trace，记录 batch objective、基线和新的恢复点 -### 当前决策（RP-019） +### 当前决策（RP-020） -- PR review 结果以 GitHub latest-head open threads 为准；即便 active tracking 曾记录“无 open thread”，也必须按新抓取结果回写。 - 对 Markdown inline code 中的 C# 泛型示例，必须直接写真实的 `` 语法，不能在反引号内部再写 `<` / `>`，否则 VitePress 会把 entity 当作字面量展示。 -- 当 latest-head review 命中某个文档表述问题时，应顺手扫描同一批 PR 已改动文档中的同类模式，避免只消掉单条 thread 却把相同渲染缺陷留在相邻页面。 -- 当前本地修复完成后，下一次 GitHub 侧复核需要基于新提交/新 head commit，而不是旧的 PR review 快照。 +- 当一个渲染热点模式可以用本地正则直接衡量时，优先把该模式收敛为一个小批次并一次性清空命中列表，而不是只修单页。 +- 对文档治理批处理，主 stop condition 采用“热点列表耗尽”，次级 stop condition 采用“相对基线的分支 diff 不接近大批次阈值”。 -### 当前验证（RP-019） +### 当前验证（RP-020） -- 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 '`[^`]*<[^`]*`|`[^`]*>[^`]*`' 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 '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'` + - 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。 - 构建校验： - `bun run build`（工作目录：`docs/`） - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。 -### 归档摘要（RP-018） +### 归档摘要（RP-019） -- 使用 `$gframework-pr-review` 重新复核当前分支 PR `#272`。 -- latest-head review 命中 `GFramework.Godot.SourceGenerators/README.md:135` 的错误命名空间引用，并已在本地修正。 -- README 校验与 `docs/` 站点构建通过，待新提交推送后回 GitHub 侧确认 open thread 消失。 +- 使用 `$gframework-pr-review` 重新抓取 PR `#272` 后，定位到 `docs/zh-CN/godot/setting.md` 的 inline code HTML entity 渲染问题。 +- 顺手扫描当前 PR 已改动的相邻 Godot 文档，又在 `docs/zh-CN/godot/storage.md` 发现同型问题，并已一起修正。 +- `docs/` 站点构建通过。 ### 归档指针 @@ -55,4 +46,4 @@ ### 下一步 1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。 -2. 如果 PR `#272` 的 `Title check` 仍需要处理，到 GitHub 上把标题改成更具体的文档治理描述。 +2. 若继续执行文档治理批处理，优先排查下一类低风险渲染 / 链接热点，而不是扩成跨模块大波次。 diff --git a/docs/zh-CN/core/functional.md b/docs/zh-CN/core/functional.md index f483965e..8de4d837 100644 --- a/docs/zh-CN/core/functional.md +++ b/docs/zh-CN/core/functional.md @@ -17,7 +17,7 @@ GFramework.Core 提供了一套完整的函数式编程工具，帮助开发者 ### Option 类型 -`Option<T>` 表示可能存在或不存在的值，用于替代 null 引用。它有两种状态： +`Option` 表示可能存在或不存在的值，用于替代 null 引用。它有两种状态： - **Some**：包含一个值 - **None**：不包含值 @@ -26,7 +26,7 @@ GFramework.Core 提供了一套完整的函数式编程工具，帮助开发者 ### Result 类型 -`Result<T>` 表示操作的结果，可能是成功值或失败异常。它有三种状态： +`Result` 表示操作的结果，可能是成功值或失败异常。它有三种状态： - **Success**：操作成功，包含返回值 - **Faulted**：操作失败，包含异常信息 @@ -586,14 +586,14 @@ public async Task> ProcessRequestAsync(Request request) ### Option vs Nullable -**Q: Option 和 Nullable<T> 有什么区别？** +**Q: Option 和 `Nullable` 有什么区别？** A: -- `Nullable<T>` 只能用于值类型，`Option<T>` 可用于任何类型 -- `Option<T>` 提供丰富的函数式操作（Map、Bind、Filter 等） -- `Option<T>` 强制显式处理"无值"情况，更安全 -- `Option<T>` 可以与 Result 等其他函数式类型组合 +- `Nullable` 只能用于值类型，`Option` 可用于任何类型 +- `Option` 提供丰富的函数式操作（Map、Bind、Filter 等） +- `Option` 强制显式处理"无值"情况，更安全 +- `Option` 可以与 Result 等其他函数式类型组合 ### Result vs Exception diff --git a/docs/zh-CN/tutorials/functional-programming.md b/docs/zh-CN/tutorials/functional-programming.md index 33a973e9..bd7a2bf1 100644 --- a/docs/zh-CN/tutorials/functional-programming.md +++ b/docs/zh-CN/tutorials/functional-programming.md @@ -121,7 +121,7 @@ namespace MyGame.Services **代码说明**： -- `Option<T>` 明确表示值可能不存在，避免 NullReferenceException +- `Option` 明确表示值可能不存在，避免 NullReferenceException - `Match` 强制处理两种情况，不会遗漏 null 检查 - `Map` 和 `Bind` 实现链式转换，代码更简洁 - `Filter` 可以安全地过滤值 @@ -250,7 +250,7 @@ namespace MyGame.Services **代码说明**： -- `Result<T>` 将错误作为值返回，而不是抛出异常 +- `Result` 将错误作为值返回，而不是抛出异常 - `Result.Try` 自动捕获异常并转换为 Result - `Bind` 可以链接多个可能失败的操作 - `Match` 强制处理成功和失败两种情况 From 148cfe14b0f5add5517a5090e25b012e4cc4cc62 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 19:22:45 +0800 Subject: [PATCH 2/6] =?UTF-8?q?docs(skills):=20=E6=98=8E=E7=A1=AE=E6=89=B9?= =?UTF-8?q?=E5=A4=84=E7=90=86=E9=98=88=E5=80=BC=E9=80=9F=E8=AE=B0=E8=AF=AD?= =?UTF-8?q?=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 gframework-batch-boot skill，明确纯数字速记默认按当前分支相对远程 origin/main 的累计 diff 计算 - 补充文件数与代码行数双阈值的 OR 语义，并将无管道的 75 2000 作为推荐写法 - 同步更新 skills README 与 documentation governance tracking/trace，记录本轮规则收口与恢复点 --- .agents/skills/README.md | 14 ++++++ .agents/skills/gframework-batch-boot/SKILL.md | 41 +++++++++++++++++ ...ation-full-coverage-governance-tracking.md | 18 ++++++-- ...entation-full-coverage-governance-trace.md | 45 ++++++++++--------- 4 files changed, 92 insertions(+), 26 deletions(-) diff --git a/.agents/skills/README.md b/.agents/skills/README.md index 7b226bd3..e7558e39 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -46,9 +46,23 @@ /gframework-batch-boot ``` +批处理阈值速记： + +```bash +/gframework-batch-boot 75 +/gframework-batch-boot 75 2000 +``` + +- 单个数字默认表示“分支相对基线接近多少个文件变更时停止” +- 单个数字默认表示“当前分支全部提交相对远程 `origin/main` 接近多少个文件变更时停止” +- 两个数字默认表示“当前分支全部提交相对远程 `origin/main` 的 `文件数 OR 变更行数`”，顺序固定为 ` ` +- 不推荐写 `/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 ``` diff --git a/.agents/skills/gframework-batch-boot/SKILL.md b/.agents/skills/gframework-batch-boot/SKILL.md index 95cf0267..860ca496 100644 --- 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 ...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 ...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 ` ` +- `$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.` 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 5dda9d86..f9bfadaf 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,9 +12,10 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-020` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-021` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： + - 为 `gframework-batch-boot` 明确数字速记阈值语义，避免把“本轮新增文件数”与“整条分支 diff 阈值”混淆 - 保持 `Core` functional docs surface 的 inline code / 泛型示例在 VitePress 下按真实 C# 语法渲染 - 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述 - 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性 @@ -42,6 +43,11 @@ `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处。 - 上述 8 处 inline code 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 已统一改为真实 泛型写法，避免在 VitePress 中显示字面量 HTML entity。 +- `2026-04-23` 根据本轮使用反馈，已为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 + `.agents/skills/README.md` 补充数字速记阈值语义： + - `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止” + - `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止” + - `75 | 2000` 仅作为可理解的 OR 写法保留，不再作为推荐写法，以避免与 shell pipe 混淆 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地 文件缺陷。 @@ -70,14 +76,18 @@ - 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。 - `2026-04-23` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'` - 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。 +- `2026-04-23` `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md` 与 `sed -n '1,220p' .agents/skills/README.md` + - 结果：确认原文仅描述自然语言 stop condition，没有定义数字速记或多阈值 OR 语义；现已补齐。 - `2026-04-23` `bun run build`（工作目录：`docs/`） - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。 ## 下一步 -1. 对 `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 继续做下一类低风险 Markdown 渲染巡检，优先排查 code span 内 +1. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖 + 常见分支阈值场景。 +2. 对 `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 继续做下一类低风险 Markdown 渲染巡检，优先排查 code span 内 的 HTML entity、站点内链接和标题锚点是否仍与当前页面结构一致。 -2. 若后续分支继续调整 `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 是否仍保持同一套职责边界。 -3. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、 +4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、 `docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。 diff --git a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md index 5e73a5fd..fb6c4923 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,39 +2,40 @@ ## 2026-04-23 -### 当前恢复点：RP-020 +### 当前恢复点：RP-021 -- 按 `$gframework-batch-boot` 继续执行 `documentation-full-coverage-governance`。 -- 将这轮批处理目标定义为“清理 README / `docs/zh-CN` / 模块 README 中仍会在 inline code 里被字面渲染的 HTML 泛型实体”。 -- 基线选择为 `origin/main` `aa879d2`（`2026-04-23T17:51:41+08:00`）；当前分支 `docs/sdk-update-documentation` - 与该基线零差异，适合继续做小批次文档治理。 -- 以 `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'` 扫描后，确认剩余热点只在 - `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md`，共 8 处。 +- 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。 +- 本轮目标定义为“为 `$gframework-batch-boot` 补齐数字速记 stop condition 语义，并消除分支 diff 阈值的歧义”。 - 本轮执行的修复： - - 将 `docs/zh-CN/core/functional.md` 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 改为真实泛型写法 - - 将 `docs/zh-CN/tutorials/functional-programming.md` 中的 `Option<T>`、`Result<T>` 改为真实泛型写法 - - 同步更新 active tracking / trace，记录 batch objective、基线和新的恢复点 + - 为 `.agents/skills/gframework-batch-boot/SKILL.md` 增加 `Shorthand Stop-Condition Syntax` + - 明确 `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止” + - 明确 `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止” + - 明确 `75 | 2000` 只作为可理解的 OR 输入保留，推荐统一归一化为无 `|` 版本 + - 为 `.agents/skills/README.md` 同步补充公开入口示例与速记说明 +- 本轮执行的修复： + - 同步更新 active tracking / trace，记录该 skill 语义收口和新的恢复点 -### 当前决策（RP-020） +### 当前决策（RP-021） -- 对 Markdown inline code 中的 C# 泛型示例，必须直接写真实的 `` 语法，不能在反引号内部再写 - `<` / `>`，否则 VitePress 会把 entity 当作字面量展示。 -- 当一个渲染热点模式可以用本地正则直接衡量时，优先把该模式收敛为一个小批次并一次性清空命中列表，而不是只修单页。 -- 对文档治理批处理，主 stop condition 采用“热点列表耗尽”，次级 stop condition 采用“相对基线的分支 diff 不接近大批次阈值”。 +- 对 `$gframework-batch-boot` 的纯数字速记，默认第一位数字绑定“文件数阈值”，第二位数字绑定“行数阈值”。 +- 对 `$gframework-batch-boot` 的纯数字速记，默认比较口径固定为“当前分支全部提交相对远程 `origin/main` 的累计 diff”。 +- 多个数字阈值的默认逻辑为 OR，而不是 AND；否则不符合“任一 reviewability 阈值接近上限就停”的批处理目标。 +- 为避免 shell 语义干扰，文档与后续回复中应优先使用无 `|` 的规范写法，即 `$gframework-batch-boot 75 2000`。 -### 当前验证（RP-020） +### 当前验证（RP-021） -- 同类模式巡检： - - `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'` - - 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。 +- skill 文档巡检： + - `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md` + - `sed -n '1,220p' .agents/skills/README.md` + - 结果：确认原文缺少数字速记与 OR 语义定义，现已补齐。 - 构建校验： - `bun run build`（工作目录：`docs/`） - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。 -### 归档摘要（RP-019） +### 归档摘要（RP-020） -- 使用 `$gframework-pr-review` 重新抓取 PR `#272` 后，定位到 `docs/zh-CN/godot/setting.md` 的 inline code HTML entity 渲染问题。 -- 顺手扫描当前 PR 已改动的相邻 Godot 文档，又在 `docs/zh-CN/godot/storage.md` 发现同型问题，并已一起修正。 +- 对 `README.md`、模块 README 与 `docs/zh-CN` 做 HTML entity 泛型热点清理。 +- 修复 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 中剩余的 8 处写法。 - `docs/` 站点构建通过。 ### 归档指针 From a4bb041b0d6ed0023236a768a1867c41bc565f0b Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 20:53:41 +0800 Subject: [PATCH 3/6] =?UTF-8?q?docs(documentation):=20=E8=A1=A5=E5=85=85?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E7=AB=99=E4=BB=93=E5=BA=93=E5=85=A5=E5=8F=A3?= =?UTF-8?q?=E9=93=BE=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 docs/zh-CN landing page 与 API 导航页中的 README 入口为可点击 GitHub 链接 - 修复 VitePress 对 docs 外相对链接的 dead link 构建失败 - 更新 documentation-full-coverage-governance 跟踪与轨迹以记录本轮批处理结论 --- ...ation-full-coverage-governance-tracking.md | 22 ++++++--- ...entation-full-coverage-governance-trace.md | 46 +++++++++---------- docs/zh-CN/abstractions/core-abstractions.md | 4 +- docs/zh-CN/abstractions/game-abstractions.md | 4 +- docs/zh-CN/api-reference/index.md | 12 ++--- docs/zh-CN/core/index.md | 10 ++-- docs/zh-CN/game/index.md | 6 +-- docs/zh-CN/getting-started/index.md | 6 +-- docs/zh-CN/source-generators/index.md | 8 ++-- 9 files changed, 62 insertions(+), 56 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 f9bfadaf..cdd3dc71 100644 --- a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md +++ b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md @@ -12,11 +12,11 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-021` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-022` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 为 `gframework-batch-boot` 明确数字速记阈值语义，避免把“本轮新增文件数”与“整条分支 diff 阈值”混淆 - - 保持 `Core` functional docs surface 的 inline code / 泛型示例在 VitePress 下按真实 C# 语法渲染 + - 保持 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/` @@ -48,6 +48,11 @@ - `$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 站点中的入口可达性；适合继续作为小步快跑的低风险治理模式。 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地 文件缺陷。 @@ -78,15 +83,18 @@ - 结果：命中 `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` `bun run build`（工作目录：`docs/`） - - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。 + - 结果：通过；仓库 README 外链改为 GitHub `main` blob 后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 ## 下一步 -1. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖 +1. 对 `docs/zh-CN/**` 继续做下一类低风险导航巡检，优先收口 `core/cqrs.md`、`ecs/arch.md`、`game/scene.md`、 + `game/ui.md` 与若干 source generator 专题页里剩余的裸路径 README 入口。 +2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖 常见分支阈值场景。 -2. 对 `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 继续做下一类低风险 Markdown 渲染巡检，优先排查 code span 内 - 的 HTML entity、站点内链接和标题锚点是否仍与当前页面结构一致。 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 fb6c4923..4b6011fb 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,40 +2,37 @@ ## 2026-04-23 -### 当前恢复点：RP-021 +### 当前恢复点：RP-022 - 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。 -- 本轮目标定义为“为 `$gframework-batch-boot` 补齐数字速记 stop condition 语义，并消除分支 diff 阈值的歧义”。 +- 本轮目标定义为“在不扩张语义范围的前提下，收口 docs landing / API 导航页中的裸路径仓库入口”。 - 本轮执行的修复： - - 为 `.agents/skills/gframework-batch-boot/SKILL.md` 增加 `Shorthand Stop-Condition Syntax` - - 明确 `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止” - - 明确 `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止” - - 明确 `75 | 2000` 只作为可理解的 OR 输入保留，推荐统一归一化为无 `|` 版本 - - 为 `.agents/skills/README.md` 同步补充公开入口示例与速记说明 -- 本轮执行的修复： - - 同步更新 active tracking / trace，记录该 skill 语义收口和新的恢复点 + - 将 `docs/zh-CN/getting-started/index.md` 中 `Cqrs`、`Game`、`Godot` 的仓库模块入口改为可点击链接 + - 将 `docs/zh-CN/core/index.md`、`game/index.md`、`source-generators/index.md` 的“对应模块入口”统一改为可点击链接 + - 将 `docs/zh-CN/api-reference/index.md` 中根 README 与模块 README 映射改为可点击链接 + - 将 `docs/zh-CN/abstractions/core-abstractions.md` 与 `game-abstractions.md` 的回跳入口改为可点击链接 + - 同步更新 active tracking / trace，记录新的治理切片与恢复点 -### 当前决策（RP-021） +### 当前决策（RP-022） -- 对 `$gframework-batch-boot` 的纯数字速记，默认第一位数字绑定“文件数阈值”，第二位数字绑定“行数阈值”。 -- 对 `$gframework-batch-boot` 的纯数字速记，默认比较口径固定为“当前分支全部提交相对远程 `origin/main` 的累计 diff”。 -- 多个数字阈值的默认逻辑为 OR，而不是 AND；否则不符合“任一 reviewability 阈值接近上限就停”的批处理目标。 -- 为避免 shell 语义干扰，文档与后续回复中应优先使用无 `|` 的规范写法，即 `$gframework-batch-boot 75 2000`。 +- 继续使用 `origin/main` 作为 `$gframework-batch-boot 75` 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。 +- 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。 +- 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。 +- 当 docs 页需要跳转到 `docs/` 外部的 README 时，使用 GitHub `main` 分支 blob 外链，而不是跨出 `docs/` 根目录的相对路径。 -### 当前验证（RP-021） +### 当前验证（RP-022） -- skill 文档巡检： - - `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md` - - `sed -n '1,220p' .agents/skills/README.md` - - 结果：确认原文缺少数字速记与 OR 语义定义，现已补齐。 +- 导航热点巡检： + - `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` + - 结果：命中 landing / API 导航页中的裸路径仓库入口，已按本轮批次收口 7 个页面。 - 构建校验： - `bun run build`（工作目录：`docs/`） - - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。 + - 结果：通过；将仓库 README 跳转改为 GitHub `main` blob 外链后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 -### 归档摘要（RP-020） +### 归档摘要（RP-021） -- 对 `README.md`、模块 README 与 `docs/zh-CN` 做 HTML entity 泛型热点清理。 -- 修复 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 中剩余的 8 处写法。 +- 为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 `.agents/skills/README.md` 补齐数字速记 stop condition 语义。 +- 明确 `$gframework-batch-boot 75` / `75 2000` 默认绑定 `origin/main` 累计 diff 口径。 - `docs/` 站点构建通过。 ### 归档指针 @@ -47,4 +44,5 @@ ### 下一步 1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。 -2. 若继续执行文档治理批处理，优先排查下一类低风险渲染 / 链接热点，而不是扩成跨模块大波次。 +2. 若继续执行文档治理批处理，优先排查 `core/cqrs.md`、`ecs/arch.md`、`game/scene.md`、`game/ui.md` + 与 source generator 专题页中剩余的裸路径 README 入口，而不是扩成跨模块大波次。 diff --git a/docs/zh-CN/abstractions/core-abstractions.md b/docs/zh-CN/abstractions/core-abstractions.md index 24a922ab..5f3398b8 100644 --- 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) diff --git a/docs/zh-CN/abstractions/game-abstractions.md b/docs/zh-CN/abstractions/game-abstractions.md index 196557e0..a6f14437 100644 --- 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) diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md index 94198008..c5f6a36d 100644 --- 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，还是先看教程 diff --git a/docs/zh-CN/core/index.md b/docs/zh-CN/core/index.md index d712b50b..39435bf5 100644 --- 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) diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index 4857a76c..7efe4be0 100644 --- 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) diff --git a/docs/zh-CN/getting-started/index.md b/docs/zh-CN/getting-started/index.md index 9f3dca77..50f15211 100644 --- 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 什么时候装 diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md index fbde5df3..2c10c143 100644 --- 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) From 8a117201d44739728df83c14ec274d4e89e19089 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 21:01:28 +0800 Subject: [PATCH 4/6] =?UTF-8?q?docs(documentation):=20=E6=94=B6=E5=8F=A3?= =?UTF-8?q?=E4=B8=93=E9=A2=98=E9=A1=B5README=E5=AF=BC=E8=88=AA=E5=85=A5?= =?UTF-8?q?=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新专题页推荐阅读中的 README 入口为可点击 GitHub 链接 - 修复 source-generators 与 Game/ECS/CQRS 页面中的裸路径导航 - 更新 documentation-full-coverage-governance 跟踪与轨迹以记录第二批治理结果 --- ...ation-full-coverage-governance-tracking.md | 11 +++++-- ...entation-full-coverage-governance-trace.md | 31 +++++++++++-------- .../abstractions/ecs-arch-abstractions.md | 4 +-- docs/zh-CN/core/cqrs.md | 2 +- docs/zh-CN/ecs/arch.md | 2 +- docs/zh-CN/game/scene.md | 4 +-- docs/zh-CN/game/ui.md | 4 +-- ...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 +- .../source-generators/priority-generator.md | 2 +- 13 files changed, 40 insertions(+), 30 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 cdd3dc71..2f4db2ee 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,7 +12,7 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-022` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-023` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - 保持 landing page / API 导航页中的仓库 README 入口可点击，避免读者在 docs 站点里遇到裸路径文本 @@ -53,6 +53,9 @@ `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 外链。 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地 文件缺陷。 @@ -86,13 +89,15 @@ - `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` - 结果：确认 landing / API 导航页仍有一批裸路径仓库入口；本轮已先修复 `getting-started`、`core`、`game`、 `source-generators`、`api-reference` 与两个 abstractions 页面。 +- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` + - 结果：定位第二批专题页导航热点，已修复 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、 + `game/scene.md`、`game/ui.md` 以及 6 个 `source-generators/*.md` 页面。 - `2026-04-23` `bun run build`（工作目录：`docs/`） - 结果：通过；仓库 README 外链改为 GitHub `main` blob 后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 ## 下一步 -1. 对 `docs/zh-CN/**` 继续做下一类低风险导航巡检，优先收口 `core/cqrs.md`、`ecs/arch.md`、`game/scene.md`、 - `game/ui.md` 与若干 source generator 专题页里剩余的裸路径 README 入口。 +1. 对 `docs/zh-CN/**` 继续做下一类低风险导航 / 渲染巡检，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接是否仍和页面结构一致。 2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖 常见分支阈值场景。 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 diff --git a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md index 4b6011fb..127434ca 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,38 +2,44 @@ ## 2026-04-23 -### 当前恢复点：RP-022 +### 当前恢复点：RP-023 - 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。 -- 本轮目标定义为“在不扩张语义范围的前提下，收口 docs landing / API 导航页中的裸路径仓库入口”。 +- 本轮目标定义为“继续沿用上一批的 GitHub 外链策略，收口专题页里的裸路径 README 入口”。 - 本轮执行的修复： - - 将 `docs/zh-CN/getting-started/index.md` 中 `Cqrs`、`Game`、`Godot` 的仓库模块入口改为可点击链接 - - 将 `docs/zh-CN/core/index.md`、`game/index.md`、`source-generators/index.md` 的“对应模块入口”统一改为可点击链接 - - 将 `docs/zh-CN/api-reference/index.md` 中根 README 与模块 README 映射改为可点击链接 - - 将 `docs/zh-CN/abstractions/core-abstractions.md` 与 `game-abstractions.md` 的回跳入口改为可点击链接 - - 同步更新 active tracking / trace，记录新的治理切片与恢复点 + - 将 `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-022） +### 当前决策（RP-023） - 继续使用 `origin/main` 作为 `$gframework-batch-boot 75` 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。 - 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。 - 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。 - 当 docs 页需要跳转到 `docs/` 外部的 README 时，使用 GitHub `main` 分支 blob 外链，而不是跨出 `docs/` 根目录的相对路径。 +- 第二批继续沿用同一外链策略，避免在同一 docs surface 中混用“裸路径 / 相对死链 / GitHub 外链”三套入口风格。 -### 当前验证（RP-022） +### 当前验证（RP-023） - 导航热点巡检： - `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` - 结果：命中 landing / API 导航页中的裸路径仓库入口，已按本轮批次收口 7 个页面。 +- 第二批专题页巡检： + - `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` + - 结果：命中 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、`game/scene.md`、 + `game/ui.md` 与 6 个 `source-generators/*.md` 专题页，均已修复。 - 构建校验： - `bun run build`（工作目录：`docs/`） - 结果：通过；将仓库 README 跳转改为 GitHub `main` blob 外链后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 -### 归档摘要（RP-021） +### 归档摘要（RP-022） - 为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 `.agents/skills/README.md` 补齐数字速记 stop condition 语义。 - 明确 `$gframework-batch-boot 75` / `75 2000` 默认绑定 `origin/main` 累计 diff 口径。 -- `docs/` 站点构建通过。 +- 完成第一批 landing / API 导航页 README 外链治理，并通过 `docs/` 站点构建。 ### 归档指针 @@ -44,5 +50,4 @@ ### 下一步 1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。 -2. 若继续执行文档治理批处理，优先排查 `core/cqrs.md`、`ecs/arch.md`、`game/scene.md`、`game/ui.md` - 与 source generator 专题页中剩余的裸路径 README 入口，而不是扩成跨模块大波次。 +2. 若继续执行文档治理批处理，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接热点，而不是扩成跨模块大波次。 diff --git a/docs/zh-CN/abstractions/ecs-arch-abstractions.md b/docs/zh-CN/abstractions/ecs-arch-abstractions.md index c477d310..72c631d4 100644 --- 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) diff --git a/docs/zh-CN/core/cqrs.md b/docs/zh-CN/core/cqrs.md index 28653d22..3431e1d9 100644 --- a/docs/zh-CN/core/cqrs.md +++ b/docs/zh-CN/core/cqrs.md @@ -186,4 +186,4 @@ RegisterCqrsPipelineBehavior>(); - 架构入口：[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) diff --git a/docs/zh-CN/ecs/arch.md b/docs/zh-CN/ecs/arch.md index 47fd2e95..46c1789b 100644 --- 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) diff --git a/docs/zh-CN/game/scene.md b/docs/zh-CN/game/scene.md index ea61c67d..d394adb5 100644 --- 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) diff --git a/docs/zh-CN/game/ui.md b/docs/zh-CN/game/ui.md index 5a64d405..2dd18cd2 100644 --- 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) diff --git a/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md b/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md index fc0ebab9..cb501a3f 100644 --- 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? 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) diff --git a/docs/zh-CN/source-generators/bind-node-signal-generator.md b/docs/zh-CN/source-generators/bind-node-signal-generator.md index 0e317db7..b64ad0aa 100644 --- 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) diff --git a/docs/zh-CN/source-generators/context-aware-generator.md b/docs/zh-CN/source-generators/context-aware-generator.md index 3d9aafaf..c4e0a3d2 100644 --- 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) diff --git a/docs/zh-CN/source-generators/get-node-generator.md b/docs/zh-CN/source-generators/get-node-generator.md index 1f317486..f8843f63 100644 --- 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) diff --git a/docs/zh-CN/source-generators/godot-project-generator.md b/docs/zh-CN/source-generators/godot-project-generator.md index f4fdfaf9..499013c3 100644 --- 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) diff --git a/docs/zh-CN/source-generators/priority-generator.md b/docs/zh-CN/source-generators/priority-generator.md index 3059ddb1..62d1215c 100644 --- 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) From 45b25f429f45a976367e5b5705a64fa25fb7217f Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 21:04:02 +0800 Subject: [PATCH 5/6] =?UTF-8?q?docs(documentation):=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E6=89=B9=E5=A4=84=E7=90=86=E6=81=A2=E5=A4=8D=E7=82=B9=E6=8C=87?= =?UTF-8?q?=E6=A0=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 documentation-full-coverage-governance 跟踪中的当前分支阈值状态 - 补充 trace 对 24 个文件与 264 行变更的 stop-condition 记录 - 说明剩余热点已转为正文语义性提及，适合后续逐页复核 --- .../todos/documentation-full-coverage-governance-tracking.md | 4 +++- .../traces/documentation-full-coverage-governance-trace.md | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) 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 2f4db2ee..c769ae40 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 @@ -56,6 +56,8 @@ - `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 元数据，不是本地 文件缺陷。 @@ -97,7 +99,7 @@ ## 下一步 -1. 对 `docs/zh-CN/**` 继续做下一类低风险导航 / 渲染巡检，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接是否仍和页面结构一致。 +1. 若继续执行文档治理批处理，优先改做标题锚点、站内链接和少量非导航型裸路径引用的逐页复核，而不是继续按统一模板机械替换。 2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖 常见分支阈值场景。 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 diff --git a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md index 127434ca..ece9fc2e 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 @@ -34,6 +34,10 @@ - 构建校验： - `bun run build`（工作目录：`docs/`） - 结果：通过；将仓库 README 跳转改为 GitHub `main` blob 外链后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 +- 当前阈值状态： + - `git diff --name-only origin/main...HEAD | wc -l` => `24` + - `git diff --numstat origin/main...HEAD` 汇总 => `264` changed lines + - 结论：尚未接近 `75` 文件阈值，但剩余命中主要是正文语义性提及，当前批次在低风险模板化导航治理上可先收口。 ### 归档摘要（RP-022） From a3501c9b910c59fc011c5b8ad58f38d60d3dc0d4 Mon Sep 17 00:00:00 2001 From: GeWuYou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 23:02:02 +0800 Subject: [PATCH 6/6] =?UTF-8?q?docs(skills):=20=E6=9B=B4=E6=96=B0=20README?= =?UTF-8?q?=20=E4=B8=AD=E5=85=B3=E4=BA=8E=E6=96=87=E4=BB=B6=E5=8F=98?= =?UTF-8?q?=E6=9B=B4=E5=81=9C=E6=AD=A2=E6=9D=A1=E4=BB=B6=E7=9A=84=E8=AF=B4?= =?UTF-8?q?=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 移除了关于分支相对基线的旧说明 - 明确单个数字表示当前分支全部提交相对远程 origin/main 的文件变更数 - 详细说明两个数字表示文件数或变更行数的固定顺序 - 添加关于避免使用 | 符号的建议并说明其 OR 语义 --- .agents/skills/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.agents/skills/README.md b/.agents/skills/README.md index e7558e39..e5098a6a 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -53,7 +53,6 @@ /gframework-batch-boot 75 2000 ``` -- 单个数字默认表示“分支相对基线接近多少个文件变更时停止” - 单个数字默认表示“当前分支全部提交相对远程 `origin/main` 接近多少个文件变更时停止” - 两个数字默认表示“当前分支全部提交相对远程 `origin/main` 的 `文件数 OR 变更行数`”，顺序固定为 ` ` - 不推荐写 `/gframework-batch-boot 75 | 2000`，因为 `|` 很像 shell pipe；若用户这样写，也应按 OR 语义理解并在后续说明中归一化成无 `|` 版本