From df91d3706ba9db71737e803ef2f40f4841ecbbf1 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 08:49:41 +0800 Subject: [PATCH] =?UTF-8?q?fix(docs):=20=E4=BF=AE=E5=A4=8D=20PR=20?= =?UTF-8?q?=E8=AF=84=E5=AE=A1=E9=81=97=E7=95=99=E4=B8=8E=20Git=20=E6=8A=93?= =?UTF-8?q?=E5=8F=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修复 gframework-pr-review 在 WSL worktree 中优先使用显式 Linux Git 绑定 - 更新 CQRS 与 ECS 文档以及 skill 文案，消化 PR #271 中仍成立的 review 意见 - 归档 documentation-full-coverage-governance 历史验证记录，并补写 trace 验证结果态 --- .agents/skills/gframework-pr-review/SKILL.md | 19 ++-- .../scripts/fetch_current_pr_review.py | 42 ++++++++- ...umentation-governance-and-refresh-trace.md | 1 + ...nance-validation-history-through-rp-007.md | 77 +++++++++++++++ ...ation-full-coverage-governance-tracking.md | 93 +++++-------------- ...entation-full-coverage-governance-trace.md | 39 ++++++++ .../abstractions/ecs-arch-abstractions.md | 9 -- docs/zh-CN/ecs/index.md | 2 +- .../cqrs-handler-registry-generator.md | 4 + 9 files changed, 196 insertions(+), 90 deletions(-) create mode 100644 ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md diff --git a/.agents/skills/gframework-pr-review/SKILL.md b/.agents/skills/gframework-pr-review/SKILL.md index 42ecfa95..473f9aa0 100644 --- a/.agents/skills/gframework-pr-review/SKILL.md +++ b/.agents/skills/gframework-pr-review/SKILL.md @@ -12,7 +12,9 @@ Shortcut: `$gframework-pr-review` ## Workflow 1. Read `AGENTS.md` before deciding how to validate or fix anything. -2. Resolve the current branch with Windows Git from WSL, following the repository worktree rule. +2. Resolve the current branch following the repository worktree rule: + - prefer Linux `git` with explicit `--git-dir` / `--work-tree` binding in WSL worktrees + - only fall back to `git.exe` when that executable is available and actually runnable in the current session 3. Run `scripts/fetch_current_pr_review.py` to: - locate the PR for the current branch through the GitHub PR API - fetch PR metadata, issue comments, reviews, and review comments through the GitHub API @@ -31,20 +33,20 @@ Shortcut: `$gframework-pr-review` ## Commands - Default: - - `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py` + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py` - Recommended machine-readable workflow: - - `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 265 --json-output /tmp/pr265-review.json` + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 265 --json-output /tmp/pr265-review.json` - `jq '.coderabbit_review.outside_diff_comments' /tmp/pr265-review.json` - Force a PR number: - - `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253` + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253` - Machine-readable output: - - `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json` + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json` - Write machine-readable output to a file instead of stdout: - - `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253 --format json --json-output /tmp/pr253-review.json` + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253 --format json --json-output /tmp/pr253-review.json` - Inspect only a high-signal section: - - `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253 --section outside-diff` + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253 --section outside-diff` - Narrow text output to one path fragment: - - `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253 --section outside-diff --path GFramework.Core/Events/Event.cs` + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253 --section outside-diff --path GFramework.Core/Events/Event.cs` ## Output Expectations @@ -67,6 +69,7 @@ The script should produce: - If the current branch has no matching public PR, report that clearly instead of guessing. - If GitHub access fails because of proxy configuration, rerun the fetch with proxy variables removed. +- If the current WSL session resolves `git.exe` but cannot execute it cleanly, keep using the explicit Linux worktree binding instead of retrying Windows Git. - Prefer GitHub API results over PR HTML. The PR HTML page is now a fallback/debugging source, not the primary source of truth. - If the summary block and the latest head review threads disagree, trust the latest unresolved head-review threads and treat older summary findings as stale until re-verified locally. - Do not assume every AI reviewer behaves like CodeRabbit. `greptile-apps[bot]` findings may exist only as latest-head review threads, without CodeRabbit-style issue comments or folded review-body sections. diff --git a/.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py b/.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py index a2e98cd7..ee9d870c 100644 --- a/.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py +++ b/.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py @@ -21,8 +21,11 @@ from typing import Any OWNER = "GeWuYou" REPO = "GFramework" +WORKTREE_ROOT_DIRECTORY_NAME = "GFramework-WorkTree" DEFAULT_WINDOWS_GIT = "/mnt/d/Tool/Development Tools/Git/cmd/git.exe" GIT_ENVIRONMENT_KEY = "GFRAMEWORK_WINDOWS_GIT" +GIT_DIR_ENVIRONMENT_KEY = "GFRAMEWORK_GIT_DIR" +WORK_TREE_ENVIRONMENT_KEY = "GFRAMEWORK_WORK_TREE" USER_AGENT = "codex-gframework-pr-review" CODERABBIT_LOGIN = "coderabbitai[bot]" GREPTILE_LOGIN = "greptile-apps[bot]" @@ -83,6 +86,43 @@ def resolve_git_command() -> str: raise RuntimeError(f"No usable git executable found. Set {GIT_ENVIRONMENT_KEY} to override it.") +def find_repository_root(start_path: Path) -> Path | None: + """Locate the repository root by walking parent directories for repo markers.""" + for candidate in (start_path, *start_path.parents): + if (candidate / "AGENTS.md").exists() and (candidate / ".ai/environment/tools.ai.yaml").exists(): + return candidate + + return None + + +def resolve_worktree_git_dir(repository_root: Path) -> Path | None: + """Resolve the main-repository worktree gitdir for this WSL worktree layout.""" + if repository_root.parent.name != WORKTREE_ROOT_DIRECTORY_NAME: + return None + + primary_repository_root = repository_root.parent.parent / REPO + candidate_git_dir = primary_repository_root / ".git" / "worktrees" / repository_root.name + return candidate_git_dir if candidate_git_dir.exists() else None + + +def resolve_git_invocation() -> list[str]: + """Resolve the git command arguments, preferring explicit WSL worktree binding.""" + configured_git_dir = os.environ.get(GIT_DIR_ENVIRONMENT_KEY) + configured_work_tree = os.environ.get(WORK_TREE_ENVIRONMENT_KEY) + linux_git = shutil.which("git") + + if configured_git_dir and configured_work_tree and linux_git: + return [linux_git, f"--git-dir={configured_git_dir}", f"--work-tree={configured_work_tree}"] + + repository_root = find_repository_root(Path.cwd()) + if repository_root is not None and linux_git: + worktree_git_dir = resolve_worktree_git_dir(repository_root) + if worktree_git_dir is not None: + return [linux_git, f"--git-dir={worktree_git_dir}", f"--work-tree={repository_root}"] + + return [resolve_git_command()] + + def resolve_request_timeout_seconds() -> int: """Return the GitHub request timeout in seconds.""" configured_timeout = os.environ.get(REQUEST_TIMEOUT_ENVIRONMENT_KEY) @@ -113,7 +153,7 @@ def run_command(args: list[str]) -> str: def get_current_branch() -> str: """Return the current git branch name.""" - return run_command([resolve_git_command(), "rev-parse", "--abbrev-ref", "HEAD"]) + return run_command([*resolve_git_invocation(), "rev-parse", "--abbrev-ref", "HEAD"]) def open_url(url: str, accept: str) -> tuple[str, Any]: diff --git a/ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md b/ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md index e4deadfe..3709cc23 100644 --- a/ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md +++ b/ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md @@ -19,6 +19,7 @@ ### 验证 - `cd docs && bun run build` +- 结果：通过；无构建失败，主题满足归档前的最终验证要求 ### 下一步 diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md new file mode 100644 index 00000000..3a955053 --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md @@ -0,0 +1,77 @@ +# Documentation Full Coverage Governance Validation History Through RP-007 + +以下内容从 active tracking 中迁出，用于保留 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-001` 到 +`DOCUMENTATION-FULL-COVERAGE-GOV-RP-007` 的详细验证历史。默认 `boot` 只需要读取 active tracking 中的最新摘要； +若需要追溯早期验证命令与结果，再回到本归档文件。 + +## 详细验证历史 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/index.md` +- 结果：通过 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md` +- 结果：通过 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` +- 结果：通过 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` +- 结果：通过 +- 备注：`2026-04-22` 在补充 Core XML inventory 后重新验证 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/core-abstractions.md` +- 结果：通过 +- 备注：`2026-04-22` 在补充 Core.Abstractions XML inventory 后重新验证 +- `cd docs && bun run build` +- 结果：通过 +- 备注：`2026-04-22` 重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 +- `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` +- 结果：通过 +- 备注：`0 Warning(s) / 0 Error(s)` +- `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` +- 结果：通过 +- 备注：`0 Warning(s) / 0 Error(s)` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/index.md` +- 结果：通过 +- 备注：`2026-04-22` 在重写 ECS landing 后重新验证 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md` +- 结果：通过 +- 备注：`2026-04-22` 在重写 Arch ECS 专题页后重新验证 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md` +- 结果：通过 +- 备注：`2026-04-22` 在补充抽象页 XML inventory 后重新验证 +- `cd docs && bun run build` +- 结果：通过 +- 备注：`2026-04-22` 在 Ecs 波次重写后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` +- 结果：通过 +- 备注：`2026-04-22` 在重写 `Cqrs` family landing 后重新验证 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` +- 结果：通过 +- 备注：`2026-04-22` 在新增 `Cqrs.SourceGenerators` 专题页后验证通过 +- `python3` 轻量 XML inventory 扫描 +- 结果：通过 +- 备注：`2026-04-22` 确认 `GFramework.Cqrs` 的 `Internal/` 为 `14/14`、`GFramework.Cqrs.SourceGenerators/Cqrs/` 为 `3/3`、`GFramework.Cqrs.Abstractions/Cqrs/` 为 `20/20` +- `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Cqrs.SourceGenerators/GFramework.Cqrs.SourceGenerators.csproj -c Release -p:RestoreFallbackFolders=` +- 结果：通过 +- 备注：保留既有 `NU1900` 与 `MA0051` warnings；无新增编译错误 +- `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Cqrs/GFramework.Cqrs.csproj -c Release` +- 结果：失败 +- 备注：当前环境会命中失效的 Windows fallback package folder，并在多目标 inner build 阶段触发 `MSB4276` / `MSB4018`；失败原因已记录为环境阻塞，不属于本轮文档改动回归 +- `cd docs && bun run build` +- 结果：通过 +- 备注：`2026-04-22` 在 `Cqrs` 波次文档刷新后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/game-abstractions.md` +- 结果：通过 +- 备注：`2026-04-23` 在重写 `Game.Abstractions` 页面后验证通过 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md` +- 结果：通过 +- 备注：`2026-04-23` 在补充 frontmatter 与 XML inventory 后重新验证 +- `python3` 轻量 XML inventory 扫描 +- 结果：通过 +- 备注：`2026-04-23` 确认 `GFramework.Game` 为 `56/56`、`GFramework.Game.Abstractions` 为 `80/80`、`GFramework.Game.SourceGenerators` 为 `2/2` +- `cd docs && bun run build` +- 结果：通过 +- 备注：`2026-04-23` 在 `Game` 波次文档刷新后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 +- `cd docs && bun run build` +- 结果：通过 +- 备注：`2026-04-23` 在更新 `AGENTS.md` 的 WSL Git 优先级后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 +- `cd docs && bun run build` +- 结果：通过 +- 备注：`2026-04-23` 在推进 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-007`、回写 `Game` family 巡检结论后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 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 410e4924..157f7b91 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,16 +12,23 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-007` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-008` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 完成 `Game` family 巡检，确认 `config-system`、`scene`、`ui` 与 `source-generators` 入口没有再次偏离当前源码与 README + - 消化 PR #271 的 latest-head review follow-up，修正仍在本地成立的 docs / skill / ai-plan 问题 + - 将 active tracking 的重复验证明细迁出默认 boot 路径，只保留最新可恢复摘要 - 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic - - 继续把 active topic 收敛为可恢复入口，而不是把详细历史长期堆在默认 boot 路径 ## 当前状态摘要 - 已归档的 `documentation-governance-and-refresh` 仅保留为历史证据，不再作为默认 `boot` 入口 +- 本轮已消化的 PR #271 review follow-up： + - 为 `.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py` 补齐 WSL worktree 下的显式 Linux Git 绑定，避免 `git.exe` 在当前会话触发 `Exec format error` + - 同步更新 `.agents/skills/gframework-pr-review/SKILL.md`，改为与 `AGENTS.md` 一致的 Git 策略，并把命令示例统一到 `.agents/...` 路径 + - 为 `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` 补充 marker 类型放置与命名约定说明 + - 从 `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 删除误放的 source-generator 内部模块提醒，并微调 `docs/zh-CN/ecs/index.md` 的边界说明语序 + - 为 `ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md` 的归档验证补写结果态 + - 将 RP-001 至 RP-007 的详细验证历史迁入 `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md` - 本轮已确认的消费属性结论： - `GFramework.Ecs.Arch.Abstractions`：可打包直接消费模块，需要 README 和文档入口 - `GFramework.Core.SourceGenerators.Abstractions`：`IsPackable=false`，按内部支撑模块处理 @@ -96,78 +103,22 @@ ## 验证说明 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/index.md` +- 详细验证历史已归档到 `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md` +- `2026-04-23` `python3 -B -c "from pathlib import Path; compile(Path('.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py').read_text(encoding='utf-8'), '.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py', 'exec')"` - 结果：通过 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md` +- `2026-04-23` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` +- 结果：通过；成功抓取 PR `#271`，并确认当前 latest-head review threads 为 `4` 条 open +- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` - 结果：通过 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` +- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/index.md` - 结果：通过 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` +- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md` - 结果：通过 -- 备注：`2026-04-22` 在补充 Core XML inventory 后重新验证 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/core-abstractions.md` -- 结果：通过 -- 备注：`2026-04-22` 在补充 Core.Abstractions XML inventory 后重新验证 -- `cd docs && bun run build` -- 结果：通过 -- 备注：`2026-04-22` 重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 -- `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` -- 结果：通过 -- 备注：`0 Warning(s) / 0 Error(s)` -- `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` -- 结果：通过 -- 备注：`0 Warning(s) / 0 Error(s)` -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/index.md` -- 结果：通过 -- 备注：`2026-04-22` 在重写 ECS landing 后重新验证 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md` -- 结果：通过 -- 备注：`2026-04-22` 在重写 Arch ECS 专题页后重新验证 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md` -- 结果：通过 -- 备注：`2026-04-22` 在补充抽象页 XML inventory 后重新验证 -- `cd docs && bun run build` -- 结果：通过 -- 备注：`2026-04-22` 在 Ecs 波次重写后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` -- 结果：通过 -- 备注：`2026-04-22` 在重写 `Cqrs` family landing 后重新验证 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` -- 结果：通过 -- 备注：`2026-04-22` 在新增 `Cqrs.SourceGenerators` 专题页后验证通过 -- `python3` 轻量 XML inventory 扫描 -- 结果：通过 -- 备注：`2026-04-22` 确认 `GFramework.Cqrs` 的 `Internal/` 为 `14/14`、`GFramework.Cqrs.SourceGenerators/Cqrs/` 为 `3/3`、`GFramework.Cqrs.Abstractions/Cqrs/` 为 `20/20` -- `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Cqrs.SourceGenerators/GFramework.Cqrs.SourceGenerators.csproj -c Release -p:RestoreFallbackFolders=` -- 结果：通过 -- 备注：保留既有 `NU1900` 与 `MA0051` warnings；无新增编译错误 -- `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Cqrs/GFramework.Cqrs.csproj -c Release` -- 结果：失败 -- 备注：当前环境会命中失效的 Windows fallback package folder，并在多目标 inner build 阶段触发 `MSB4276` / `MSB4018`；失败原因已记录为环境阻塞，不属于本轮文档改动回归 -- `cd docs && bun run build` -- 结果：通过 -- 备注：`2026-04-22` 在 `Cqrs` 波次文档刷新后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/game-abstractions.md` -- 结果：通过 -- 备注：`2026-04-23` 在重写 `Game.Abstractions` 页面后验证通过 -- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md` -- 结果：通过 -- 备注：`2026-04-23` 在补充 frontmatter 与 XML inventory 后重新验证 -- `python3` 轻量 XML inventory 扫描 -- 结果：通过 -- 备注：`2026-04-23` 确认 `GFramework.Game` 为 `56/56`、`GFramework.Game.Abstractions` 为 `80/80`、`GFramework.Game.SourceGenerators` 为 `2/2` -- `cd docs && bun run build` -- 结果：通过 -- 备注：`2026-04-23` 在 `Game` 波次文档刷新后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 -- `cd docs && bun run build` -- 结果：通过 -- 备注：`2026-04-23` 在更新 `AGENTS.md` 的 WSL Git 优先级后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 -- `cd docs && bun run build` -- 结果：通过 -- 备注：`2026-04-23` 在推进 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-007`、回写 `Game` family 巡检结论后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败 +- `2026-04-23` `cd docs && bun run build` +- 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败 ## 下一步 -1. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，避免长期治理只依赖 archive 恢复 -2. 继续巡检 `Game` family 之外的高频入口页，优先关注 README / landing page / API reference 之间是否出现新的术语或包关系漂移 -3. 在后续环境治理任务中单独处理 `GFramework.Cqrs` 本地 build 的 fallback package folder 阻塞，避免影响后续代码类验证 +1. 完成本轮 PR #271 follow-up 的针对性验证与 docs build，确认 open threads 是否都已被本地收敛 +2. 推送当前分支后重新执行 `$gframework-pr-review`，确认 PR #271 的 latest-head open threads 是否按预期收敛 +3. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，避免长期治理只依赖 archive 恢复 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 c0d3ee63..220b0133 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 @@ -234,3 +234,42 @@ 1. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic 2. 若不需要迁回，则继续抽查 README / landing page / API reference 之间的 cross-link 是否出现新的漂移 + +### 当前恢复点：RP-008 + +- 使用 `$gframework-pr-review` 抓取当前分支 PR `#271` 后，确认 latest head review threads 仍有 `4` 条 open： + - `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` 的 marker 类型约定说明缺口 + - `docs/zh-CN/ecs/index.md` 的边界说明语序问题 + - `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 误放的 source-generator 内部模块提醒 + - `ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md` 的验证历史过长，以及 + `ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md` 缺少显式结果态 +- 在当前 WSL 会话里，`gframework-pr-review` 脚本先命中了 `git.exe` 的 `Exec format error` +- 已将 `.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py` 改为优先使用 Linux `git` 的显式 + `--git-dir` / `--work-tree` 绑定，并仅在无法建立该绑定时回退到旧的可执行解析逻辑 +- 已同步更新 `.agents/skills/gframework-pr-review/SKILL.md`，使其 Git 策略与命令示例都与当前仓库状态一致 +- 已把 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-001` 到 `RP-007` 的详细验证历史迁入 + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md` + +### 当前决策（RP-008） + +- 继续把 latest-head unresolved threads 作为主信号，只修仍在本地成立的评论，不为已失效的历史 summary 做无意义回写 +- active tracking 只保留最新验证摘要与恢复点；详细验证历史留在 topic 自己的 archive，而不是继续堆在默认 boot 路径 +- `gframework-pr-review` 的脚本行为、技能文案与 `AGENTS.md` 必须保持同一套 WSL Git 策略，避免再次出现“文档说法正确但工具实现仍跑偏”的情况 + +### 当前验证（RP-008） + +- PR review 抓取： + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`：通过 +- 脚本语法校验： + - `python3 -B -c "from pathlib import Path; compile(Path('.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py').read_text(encoding='utf-8'), '.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py', 'exec')"`：通过 +- 文档校验： + - `validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过 + - `validate-all.sh docs/zh-CN/ecs/index.md`：通过 + - `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过 +- 构建校验： + - `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败 + +### 下一步 + +1. 提交本轮 PR review follow-up +2. 推送当前分支后重新执行 `$gframework-pr-review`，观察 PR #271 的 open threads 是否收敛 diff --git a/docs/zh-CN/abstractions/ecs-arch-abstractions.md b/docs/zh-CN/abstractions/ecs-arch-abstractions.md index bca589c1..c477d310 100644 --- a/docs/zh-CN/abstractions/ecs-arch-abstractions.md +++ b/docs/zh-CN/abstractions/ecs-arch-abstractions.md @@ -92,12 +92,3 @@ var options = new ArchOptions 3. 回到对应模块 README： - `GFramework.Ecs.Arch.Abstractions/README.md` - `GFramework.Ecs.Arch/README.md` - -## 边界提醒 - -- `GFramework.Core.SourceGenerators.Abstractions` -- `GFramework.Godot.SourceGenerators.Abstractions` -- `GFramework.SourceGenerators.Common` - -这些目录当前都不是独立消费模块，而是源码生成器家族的内部支撑组件。它们不属于抽象接口栏目里的独立采用入口， -应分别跟随 `Core.SourceGenerators`、`Godot.SourceGenerators` 或其他生成器模块的 README 与专题页维护。 diff --git a/docs/zh-CN/ecs/index.md b/docs/zh-CN/ecs/index.md index 2c47e942..b2b7e332 100644 --- a/docs/zh-CN/ecs/index.md +++ b/docs/zh-CN/ecs/index.md @@ -131,6 +131,6 @@ public sealed class GameLoop ## 边界说明 -- 当前仓库没有交付其他可直接消费的 ECS 运行时包；旧文档里把“可能支持的其他 ECS 框架”写成现有能力会误导采用路径。 +- 当前仓库没有交付其他可直接消费的 ECS 运行时包；旧文档把“未来可能支持的其他 ECS 框架”写成现有能力，会误导采用路径。 - `GFramework.Ecs.Arch.Abstractions` 负责“边界”，`GFramework.Ecs.Arch` 负责“默认实现”。 - 站内页面只维护可构建的 docs 链路；仓库根 README 和模块 README 继续承担包目录入口职责。 diff --git a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md index 3069b7d0..c30d3869 100644 --- a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md +++ b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md @@ -67,6 +67,10 @@ RegisterCqrsHandlersFromAssemblies( ]); ``` +文档示例统一用 marker 类型承载程序集引用。框架本身不要求固定目录或固定命名，但团队实践里可以把这类空 marker +集中放在每个业务程序集自己的 `Application/Markers` 或等价目录，并采用 `InventoryCqrsMarker` 这类能直接看出来源 +的名字，避免多人协作时拿无关业务类型充当程序集定位锚点。 + ## 运行时如何消费生成结果 `Cqrs` runtime 当前的注册顺序是：