Merge pull request #331 from GeWuYou/fix/package-validation-guard

fix(release): 前移发布包清单校验

.agents/skills/README.md

@@ -0,0 +1,89 @@
+# GFramework Skills
+
+公开入口目前包含 `gframework-doc-refresh` 与 `gframework-batch-boot`。
+
+## 公开入口
+
+### `gframework-doc-refresh`
+
+按源码模块驱动文档刷新，而不是按 `guide`、`tutorial`、`api` 等类型拆入口。
+
+适用场景：
+
+- 刷新某个模块的 landing page
+- 复核专题页是否与源码、测试、README 一致
+- 评估是否需要补 API reference 或教程
+- 在 adoption path 不清晰时引入 `ai-libs/` 消费者接法作为补充证据
+
+推荐调用：
+
+```bash
+/gframework-doc-refresh <module>
+```
+
+示例：
+
+```bash
+/gframework-doc-refresh Core
+/gframework-doc-refresh Godot.SourceGenerators
+/gframework-doc-refresh Cqrs
+```
+
+### `gframework-batch-boot`
+
+在 `gframework-boot` 的基础上，自动推进可分批执行的重复性任务，不需要人工一轮轮重新触发。
+
+适用场景：
+
+- analyzer warning reduction
+- 大批量测试结构收口
+- 分模块文档刷新 wave
+- 任何有明确 stop condition 的多批次任务
+
+推荐调用：
+
+```bash
+/gframework-batch-boot <task-or-stop-condition>
+```
+
+批处理阈值速记：
+
+```bash
+/gframework-batch-boot 75
+/gframework-batch-boot 75 2000
+```
+
+- 单个数字默认表示“当前分支全部提交相对远程 `origin/main` 接近多少个文件变更时停止”
+- 两个数字默认表示“当前分支全部提交相对远程 `origin/main` 的 `文件数 OR 变更行数`”，顺序固定为 `<files> <lines>`
+- 不推荐写 `/gframework-batch-boot 75 | 2000`，因为 `|` 很像 shell pipe；若用户这样写，也应按 OR 语义理解并在后续说明中归一化成无 `|` 版本
+
+示例：
+
+```bash
+/gframework-batch-boot 75
+/gframework-batch-boot 75 2000
+/gframework-batch-boot continue analyzer warning reduction until branch diff vs origin/main approaches 75 files
+/gframework-batch-boot keep refactoring repetitive source-generator tests in bounded batches
+```
+
+## 共享资源
+
+- `_shared/DOCUMENTATION_STANDARDS.md`
+  - 统一的文档规则、证据顺序与验证要求
+- `_shared/module-map.json`
+  - 机器可读的模块映射表
+- `_shared/module-config.sh`
+  - 轻量 shell 辅助函数
+
+## 内部资源
+
+`gframework-doc-refresh/` 下包含：
+
+- `references/`
+  - 模块选择、证据顺序、输出策略
+- `templates/`
+  - landing page、专题页、API reference、教程模板
+- `scripts/`
+  - 模块扫描与文档验证脚本
+
+旧 `vitepress-*` skills 不再作为并列公开入口保留。

.agents/skills/_shared/DOCUMENTATION_STANDARDS.md

@@ -0,0 +1,126 @@
+# GFramework 文档编写规范
+
+本文件只保留跨模块稳定生效的写作与校验规则，不再维护容易失真的固定页面清单。
+
+模块到源码、测试、README、`docs/zh-CN` 栏目以及 `ai-libs/` 参考入口的映射，统一以
+`.agents/skills/_shared/module-map.json` 为准。
+
+## 证据顺序
+
+统一按以下顺序判断文档应写什么、删什么、保留什么：
+
+1. 源码、公开 XML docs、`*.csproj`
+2. 对应测试和 snapshot
+3. 模块 `README.md`
+4. 当前 `docs/zh-CN` 页面
+5. `ai-libs/` 下已验证的消费者项目
+6. 归档文档，仅在前述证据无法解释当前行为时回看
+
+不要把旧文档互相抄写当成“更新”。
+
+## 模块驱动规则
+
+- 先按源码模块归一化输入，再决定落到 landing page、专题页、API reference、教程还是仅做校验。
+- 如果用户给的是栏目名而不是源码模块名，先映射回模块；若仍有歧义，只给归一化建议，不直接生成文档。
+- 文档栏目是派生输出，不是主输入源。
+
+## `ai-libs/` 使用边界
+
+`ai-libs/` 只用于补消费者视角证据：
+
+- 验证真实接入目录结构
+- 查最小 wiring、扩展点装配方式
+- 给 adoption path 提供端到端例子
+
+不要用 `ai-libs/` 覆盖以下事实：
+
+- 公共 API 契约
+- 当前版本支持范围
+- Source Generator 诊断与生成语义
+
+如果 `ai-libs/` 与当前源码或测试冲突，以当前仓库实现为准，并在文档里写明迁移或兼容边界。
+
+## 公开文档边界
+
+- `README.md` 与 `docs/**` 面向框架使用者，不面向治理执行者。
+- 不要把 inventory、覆盖基线、恢复点、批处理阈值、review 线程、待补审计波次等内部治理信息写进公开页面。
+- XML、README、测试与 `ai-libs/` 证据可以驱动文档决策，但公开页面只能输出读者真正需要的内容：
+  - 模块边界
+  - 最小接入路径
+  - 推荐阅读顺序
+  - 源码 / XML / API 的入口提示
+- 如果确实需要保留治理基线、盘点结果或后续治理计划，把它写到 `ai-plan/**` 或其他 contributor-only 记录里。
+- 当页面需要引用 XML 文档时，写“应优先查看哪些类型、命名空间或契约，以及为什么”，不要写覆盖数量、盘点日期或“已覆盖 / 未覆盖”状态。
+
+## Markdown 规则
+
+### 泛型与 HTML 转义
+
+代码块外出现泛型或 XML 标签时必须转义：
+
+- `List<T>`
+- `Result<TValue, TError>`
+- `<summary>`
+- `<param>`
+
+### Frontmatter
+
+每个文档都必须包含合法 frontmatter：
+
+```yaml
+---
+title: 文档标题
+description: 1-2 句话描述当前页面解决什么问题
+---
+```
+
+### 代码块
+
+- 始终标注语言，如 `csharp`、`bash`、`json`
+- 示例只保留当前实现可追溯的最小路径
+- 必要时写中文注释解释接入原因或边界，不要堆砌与代码同步无关的注释
+
+### 链接
+
+- 只链接到当前仓库真实存在的页面
+- 站内链接优先使用 `/zh-CN/...` 形式
+- 如果文档站不允许跳出 `docs/` 根目录，就不要把仓库 README 写成站内链接
+
+## 输出优先级
+
+统一按以下顺序决定产出：
+
+1. 先修模块 README、landing page 与 adoption path
+2. 再修失真的专题页
+3. 再补 API reference
+4. 最后才补教程
+
+## 用户页检查点
+
+- 用户读完页面后，应知道怎么采用、该看哪几个入口，而不是知道当前治理批次做到哪一轮。
+- 如果一段内容删掉日期、数量、基线、治理术语后就失去价值，它大概率不该出现在公开文档里。
+- 表格优先表达“何时看什么、解决什么问题”，不要表达“当前盘点覆盖到哪里”。
+
+## 验证清单
+
+- [ ] frontmatter 正确
+- [ ] 代码块语言标记齐全
+- [ ] 泛型和 XML 标签已转义
+- [ ] 站内链接存在
+- [ ] 示例与当前实现一致
+- [ ] `ai-libs/` 只作为消费者接入参考，没有覆盖源码契约
+
+## 验证工具
+
+统一复用 `gframework-doc-refresh/scripts/` 下的校验脚本：
+
+- `validate-frontmatter.sh`
+- `validate-links.sh`
+- `validate-code-blocks.sh`
+- `validate-all.sh`
+
+需要站点级验证时，执行：
+
+```bash
+cd docs && bun run build
+```

.agents/skills/_shared/module-config.sh

@@ -0,0 +1,271 @@
+#!/bin/bash
+# 共享的模块配置
+# 机器可读映射以 .agents/skills/_shared/module-map.json 为准。
+
+normalize_module() {
+    local INPUT
+    INPUT="$(echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr '_' '-')"
+
+    case "$INPUT" in
+        core|core-runtime|runtime-core|core-module)
+            echo "Core"
+            ;;
+        core.abstractions|core-abstractions)
+            echo "Core.Abstractions"
+            ;;
+        core.sourcegenerators|core-source-generators|core-sourcegenerators)
+            echo "Core.SourceGenerators"
+            ;;
+        core.sourcegenerators.abstractions|core-source-generators-abstractions)
+            echo "Core.SourceGenerators.Abstractions"
+            ;;
+        game|game-runtime|runtime-game|game-module)
+            echo "Game"
+            ;;
+        game.abstractions|game-abstractions)
+            echo "Game.Abstractions"
+            ;;
+        game.sourcegenerators|game-source-generators)
+            echo "Game.SourceGenerators"
+            ;;
+        godot|godot-runtime|runtime-godot|godot-module)
+            echo "Godot"
+            ;;
+        godot.sourcegenerators|godot-source-generators|godot-generators)
+            echo "Godot.SourceGenerators"
+            ;;
+        godot.sourcegenerators.abstractions|godot-source-generators-abstractions)
+            echo "Godot.SourceGenerators.Abstractions"
+            ;;
+        cqrs|mediator|cqrs-module)
+            echo "Cqrs"
+            ;;
+        cqrs.abstractions|cqrs-abstractions)
+            echo "Cqrs.Abstractions"
+            ;;
+        cqrs.sourcegenerators|cqrs-source-generators)
+            echo "Cqrs.SourceGenerators"
+            ;;
+        ecs|ecs.arch|ecs-arch)
+            echo "Ecs.Arch"
+            ;;
+        ecs.arch.abstractions|ecs-arch-abstractions)
+            echo "Ecs.Arch.Abstractions"
+            ;;
+        sourcegenerators.common|source-generators-common)
+            echo "SourceGenerators.Common"
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+get_all_modules() {
+    cat <<'EOF'
+Core
+Core.Abstractions
+Core.SourceGenerators
+Core.SourceGenerators.Abstractions
+Game
+Game.Abstractions
+Game.SourceGenerators
+Godot
+Godot.SourceGenerators
+Godot.SourceGenerators.Abstractions
+Cqrs
+Cqrs.Abstractions
+Cqrs.SourceGenerators
+Ecs.Arch
+Ecs.Arch.Abstractions
+SourceGenerators.Common
+EOF
+}
+
+is_valid_module() {
+    normalize_module "$1" >/dev/null 2>&1
+}
+
+get_source_dirs() {
+    local MODULE
+    MODULE="$(normalize_module "$1")" || return 1
+
+    case "$MODULE" in
+        Core)
+            echo "GFramework.Core"
+            ;;
+        Core.Abstractions)
+            echo "GFramework.Core.Abstractions"
+            ;;
+        Core.SourceGenerators)
+            echo "GFramework.Core.SourceGenerators"
+            ;;
+        Core.SourceGenerators.Abstractions)
+            echo "GFramework.Core.SourceGenerators.Abstractions"
+            ;;
+        Game)
+            echo "GFramework.Game"
+            ;;
+        Game.Abstractions)
+            echo "GFramework.Game.Abstractions"
+            ;;
+        Game.SourceGenerators)
+            echo "GFramework.Game.SourceGenerators"
+            ;;
+        Godot)
+            echo "GFramework.Godot"
+            ;;
+        Godot.SourceGenerators)
+            echo "GFramework.Godot.SourceGenerators"
+            ;;
+        Godot.SourceGenerators.Abstractions)
+            echo "GFramework.Godot.SourceGenerators.Abstractions"
+            ;;
+        Cqrs)
+            echo "GFramework.Cqrs"
+            ;;
+        Cqrs.Abstractions)
+            echo "GFramework.Cqrs.Abstractions"
+            ;;
+        Cqrs.SourceGenerators)
+            echo "GFramework.Cqrs.SourceGenerators"
+            ;;
+        Ecs.Arch)
+            echo "GFramework.Ecs.Arch"
+            ;;
+        Ecs.Arch.Abstractions)
+            echo "GFramework.Ecs.Arch.Abstractions"
+            ;;
+        SourceGenerators.Common)
+            echo "GFramework.SourceGenerators.Common"
+            ;;
+    esac
+}
+
+get_test_projects() {
+    local MODULE
+    MODULE="$(normalize_module "$1")" || return 1
+
+    case "$MODULE" in
+        Core|Core.Abstractions)
+            echo "GFramework.Core.Tests/GFramework.Core.Tests.csproj"
+            ;;
+        Core.SourceGenerators|Core.SourceGenerators.Abstractions|Game.SourceGenerators|Cqrs.SourceGenerators|SourceGenerators.Common)
+            echo "GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj"
+            ;;
+        Game|Game.Abstractions)
+            echo "GFramework.Game.Tests/GFramework.Game.Tests.csproj"
+            ;;
+        Godot)
+            echo "GFramework.Godot.Tests/GFramework.Godot.Tests.csproj"
+            ;;
+        Godot.SourceGenerators|Godot.SourceGenerators.Abstractions)
+            echo "GFramework.Godot.SourceGenerators.Tests/GFramework.Godot.SourceGenerators.Tests.csproj"
+            ;;
+        Cqrs|Cqrs.Abstractions)
+            echo "GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj"
+            ;;
+        Ecs.Arch|Ecs.Arch.Abstractions)
+            echo "GFramework.Ecs.Arch.Tests/GFramework.Ecs.Arch.Tests.csproj"
+            ;;
+    esac
+}
+
+get_readme_paths() {
+    local MODULE
+    MODULE="$(normalize_module "$1")" || return 1
+
+    case "$MODULE" in
+        Core)
+            echo "GFramework.Core/README.md"
+            ;;
+        Core.Abstractions)
+            echo "GFramework.Core.Abstractions/README.md"
+            ;;
+        Core.SourceGenerators)
+            echo "GFramework.Core.SourceGenerators/README.md"
+            ;;
+        Core.SourceGenerators.Abstractions)
+            echo "GFramework.Core.SourceGenerators.Abstractions/README.md"
+            ;;
+        Game)
+            echo "GFramework.Game/README.md"
+            ;;
+        Game.Abstractions)
+            echo "GFramework.Game.Abstractions/README.md"
+            ;;
+        Game.SourceGenerators)
+            echo "GFramework.Game.SourceGenerators/README.md"
+            ;;
+        Godot)
+            echo "GFramework.Godot/README.md"
+            ;;
+        Godot.SourceGenerators)
+            echo "GFramework.Godot.SourceGenerators/README.md"
+            ;;
+        Godot.SourceGenerators.Abstractions)
+            echo "GFramework.Godot.SourceGenerators.Abstractions/README.md"
+            ;;
+        Cqrs)
+            echo "GFramework.Cqrs/README.md"
+            ;;
+        Cqrs.Abstractions)
+            echo "GFramework.Cqrs.Abstractions/README.md"
+            ;;
+        Cqrs.SourceGenerators)
+            echo "GFramework.Cqrs.SourceGenerators/README.md"
+            ;;
+        Ecs.Arch)
+            echo "GFramework.Ecs.Arch/README.md"
+            ;;
+        Ecs.Arch.Abstractions)
+            echo "GFramework.Ecs.Arch.Abstractions/README.md"
+            ;;
+        SourceGenerators.Common)
+            echo "GFramework.SourceGenerators.Common/README.md"
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+infer_module_from_namespace() {
+    local NAMESPACE="$1"
+
+    if [[ "$NAMESPACE" == GFramework.Core.SourceGenerators.Abstractions* ]]; then
+        echo "Core.SourceGenerators.Abstractions"
+    elif [[ "$NAMESPACE" == GFramework.Core.SourceGenerators* ]]; then
+        echo "Core.SourceGenerators"
+    elif [[ "$NAMESPACE" == GFramework.Core.Abstractions* ]]; then
+        echo "Core.Abstractions"
+    elif [[ "$NAMESPACE" == GFramework.Core* ]]; then
+        echo "Core"
+    elif [[ "$NAMESPACE" == GFramework.Game.SourceGenerators* ]]; then
+        echo "Game.SourceGenerators"
+    elif [[ "$NAMESPACE" == GFramework.Game.Abstractions* ]]; then
+        echo "Game.Abstractions"
+    elif [[ "$NAMESPACE" == GFramework.Game* ]]; then
+        echo "Game"
+    elif [[ "$NAMESPACE" == GFramework.Godot.SourceGenerators.Abstractions* ]]; then
+        echo "Godot.SourceGenerators.Abstractions"
+    elif [[ "$NAMESPACE" == GFramework.Godot.SourceGenerators* ]]; then
+        echo "Godot.SourceGenerators"
+    elif [[ "$NAMESPACE" == GFramework.Godot* ]]; then
+        echo "Godot"
+    elif [[ "$NAMESPACE" == GFramework.Cqrs.SourceGenerators* ]]; then
+        echo "Cqrs.SourceGenerators"
+    elif [[ "$NAMESPACE" == GFramework.Cqrs.Abstractions* ]]; then
+        echo "Cqrs.Abstractions"
+    elif [[ "$NAMESPACE" == GFramework.Cqrs* ]]; then
+        echo "Cqrs"
+    elif [[ "$NAMESPACE" == GFramework.Ecs.Arch.Abstractions* ]]; then
+        echo "Ecs.Arch.Abstractions"
+    elif [[ "$NAMESPACE" == GFramework.Ecs.Arch* ]]; then
+        echo "Ecs.Arch"
+    elif [[ "$NAMESPACE" == GFramework.SourceGenerators.Common* ]]; then
+        echo "SourceGenerators.Common"
+    else
+        return 1
+    fi
+}

.agents/skills/_shared/module-map.json

@@ -0,0 +1,434 @@
+{
+  "version": 1,
+  "description": "Canonical documentation refresh module map for GFramework skills.",
+  "modules": {
+    "Core": {
+      "aliases": ["core", "core-runtime", "runtime-core", "core module"],
+      "source_paths": ["GFramework.Core"],
+      "project_file": "GFramework.Core/GFramework.Core.csproj",
+      "test_projects": ["GFramework.Core.Tests/GFramework.Core.Tests.csproj"],
+      "readme_paths": ["GFramework.Core/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/core/index.md"],
+        "topics": [
+          "docs/zh-CN/core/architecture.md",
+          "docs/zh-CN/core/context.md",
+          "docs/zh-CN/core/lifecycle.md",
+          "docs/zh-CN/core/events.md",
+          "docs/zh-CN/core/property.md",
+          "docs/zh-CN/core/logging.md",
+          "docs/zh-CN/core/state-management.md",
+          "docs/zh-CN/core/coroutine.md"
+        ],
+        "fallback": [
+          "docs/zh-CN/getting-started/quick-start.md",
+          "docs/zh-CN/api-reference/index.md"
+        ]
+      },
+      "ai_libs": {
+        "paths": [
+          "ai-libs/CoreGrid/CoreGrid.csproj",
+          "ai-libs/CoreGrid/global",
+          "ai-libs/CoreGrid/docs"
+        ],
+        "search_hints": [
+          "rg -n \"Architecture|RegisterModel|RegisterSystem|BindableProperty|EventBus\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Core.Abstractions": {
+      "aliases": ["core.abstractions", "core-abstractions", "core abstractions"],
+      "source_paths": ["GFramework.Core.Abstractions"],
+      "project_file": "GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj",
+      "test_projects": ["GFramework.Core.Tests/GFramework.Core.Tests.csproj"],
+      "readme_paths": ["GFramework.Core.Abstractions/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/abstractions/core-abstractions.md"],
+        "topics": [
+          "docs/zh-CN/core/index.md",
+          "docs/zh-CN/core/architecture.md",
+          "docs/zh-CN/core/context.md"
+        ],
+        "fallback": ["docs/zh-CN/api-reference/index.md"]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/CoreGrid.csproj"],
+        "search_hints": [
+          "rg -n \"GFramework\\.Core\\.Abstractions|IArchitecture|IModel|ISystem\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Core.SourceGenerators": {
+      "aliases": [
+        "core.sourcegenerators",
+        "core-sourcegenerators",
+        "core-source-generators",
+        "core source generators"
+      ],
+      "source_paths": ["GFramework.Core.SourceGenerators"],
+      "project_file": "GFramework.Core.SourceGenerators/GFramework.Core.SourceGenerators.csproj",
+      "test_projects": ["GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj"],
+      "readme_paths": ["GFramework.Core.SourceGenerators/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/source-generators/index.md"],
+        "topics": [
+          "docs/zh-CN/source-generators/context-aware-generator.md",
+          "docs/zh-CN/source-generators/context-get-generator.md",
+          "docs/zh-CN/source-generators/priority-generator.md",
+          "docs/zh-CN/source-generators/logging-generator.md"
+        ],
+        "fallback": ["docs/zh-CN/api-reference/index.md"]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/global", "ai-libs/CoreGrid/scripts"],
+        "search_hints": [
+          "rg -n \"ContextAware|ContextGet|Priority|GeneratedLogger|Log\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Core.SourceGenerators.Abstractions": {
+      "aliases": [
+        "core.sourcegenerators.abstractions",
+        "core-source-generators-abstractions",
+        "core source generators abstractions"
+      ],
+      "source_paths": ["GFramework.Core.SourceGenerators.Abstractions"],
+      "project_file": "GFramework.Core.SourceGenerators.Abstractions/GFramework.Core.SourceGenerators.Abstractions.csproj",
+      "test_projects": ["GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj"],
+      "readme_paths": [],
+      "docs": {
+        "landing": ["docs/zh-CN/source-generators/index.md"],
+        "topics": [
+          "docs/zh-CN/source-generators/context-aware-generator.md",
+          "docs/zh-CN/source-generators/context-get-generator.md",
+          "docs/zh-CN/source-generators/priority-generator.md"
+        ],
+        "fallback": ["docs/zh-CN/api-reference/index.md"]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/global"],
+        "search_hints": [
+          "rg -n \"GFramework\\.Core\\.SourceGenerators\\.Abstractions|\\[ContextAware\\]|\\[Priority\\]\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Game": {
+      "aliases": ["game", "game-runtime", "runtime-game", "game module"],
+      "source_paths": ["GFramework.Game"],
+      "project_file": "GFramework.Game/GFramework.Game.csproj",
+      "test_projects": ["GFramework.Game.Tests/GFramework.Game.Tests.csproj"],
+      "readme_paths": ["GFramework.Game/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/game/index.md"],
+        "topics": [
+          "docs/zh-CN/game/scene.md",
+          "docs/zh-CN/game/ui.md",
+          "docs/zh-CN/game/data.md",
+          "docs/zh-CN/game/storage.md",
+          "docs/zh-CN/game/serialization.md",
+          "docs/zh-CN/game/setting.md",
+          "docs/zh-CN/game/config-system.md"
+        ],
+        "fallback": [
+          "docs/zh-CN/getting-started/quick-start.md",
+          "docs/zh-CN/api-reference/index.md"
+        ]
+      },
+      "ai_libs": {
+        "paths": [
+          "ai-libs/CoreGrid/global",
+          "ai-libs/CoreGrid/scenes",
+          "ai-libs/CoreGrid/addons"
+        ],
+        "search_hints": [
+          "rg -n \"SceneRouter|UiRouter|Setting|Storage|Serialization|Config\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Game.Abstractions": {
+      "aliases": ["game.abstractions", "game-abstractions", "game abstractions"],
+      "source_paths": ["GFramework.Game.Abstractions"],
+      "project_file": "GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj",
+      "test_projects": ["GFramework.Game.Tests/GFramework.Game.Tests.csproj"],
+      "readme_paths": ["GFramework.Game.Abstractions/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/abstractions/game-abstractions.md"],
+        "topics": [
+          "docs/zh-CN/game/index.md",
+          "docs/zh-CN/game/scene.md",
+          "docs/zh-CN/game/ui.md"
+        ],
+        "fallback": ["docs/zh-CN/api-reference/index.md"]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/global", "ai-libs/CoreGrid/scenes"],
+        "search_hints": [
+          "rg -n \"ISceneFactory|ISceneRoot|UiInteractionProfile|IUiRoot\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Game.SourceGenerators": {
+      "aliases": [
+        "game.sourcegenerators",
+        "game-source-generators",
+        "game source generators"
+      ],
+      "source_paths": ["GFramework.Game.SourceGenerators"],
+      "project_file": "GFramework.Game.SourceGenerators/GFramework.Game.SourceGenerators.csproj",
+      "test_projects": ["GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj"],
+      "readme_paths": ["GFramework.Game.SourceGenerators/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/source-generators/index.md"],
+        "topics": [
+          "docs/zh-CN/source-generators/auto-scene-generator.md",
+          "docs/zh-CN/source-generators/auto-ui-page-generator.md"
+        ],
+        "fallback": ["docs/zh-CN/game/index.md"]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/scenes", "ai-libs/CoreGrid/addons"],
+        "search_hints": [
+          "rg -n \"AutoScene|AutoUiPage|SceneRouter|UiRouter\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Godot": {
+      "aliases": ["godot", "godot-runtime", "runtime-godot", "godot module"],
+      "source_paths": ["GFramework.Godot"],
+      "project_file": "GFramework.Godot/GFramework.Godot.csproj",
+      "test_projects": ["GFramework.Godot.Tests/GFramework.Godot.Tests.csproj"],
+      "readme_paths": ["GFramework.Godot/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/godot/index.md"],
+        "topics": [
+          "docs/zh-CN/godot/architecture.md",
+          "docs/zh-CN/godot/scene.md",
+          "docs/zh-CN/godot/ui.md",
+          "docs/zh-CN/godot/storage.md",
+          "docs/zh-CN/godot/setting.md",
+          "docs/zh-CN/godot/signal.md"
+        ],
+        "fallback": [
+          "docs/zh-CN/source-generators/index.md",
+          "docs/zh-CN/api-reference/index.md"
+        ]
+      },
+      "ai_libs": {
+        "paths": [
+          "ai-libs/CoreGrid/project.godot",
+          "ai-libs/CoreGrid/global",
+          "ai-libs/CoreGrid/scenes"
+        ],
+        "search_hints": [
+          "rg -n \"AutoLoad|InputActions|Node|Signal|PackedScene|Godot\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Godot.SourceGenerators": {
+      "aliases": [
+        "godot.sourcegenerators",
+        "godot-source-generators",
+        "godot source generators",
+        "godot generators"
+      ],
+      "source_paths": ["GFramework.Godot.SourceGenerators"],
+      "project_file": "GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj",
+      "test_projects": ["GFramework.Godot.SourceGenerators.Tests/GFramework.Godot.SourceGenerators.Tests.csproj"],
+      "readme_paths": ["GFramework.Godot.SourceGenerators/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/source-generators/index.md"],
+        "topics": [
+          "docs/zh-CN/source-generators/godot-project-generator.md",
+          "docs/zh-CN/source-generators/get-node-generator.md",
+          "docs/zh-CN/source-generators/bind-node-signal-generator.md",
+          "docs/zh-CN/source-generators/auto-register-exported-collections-generator.md"
+        ],
+        "fallback": ["docs/zh-CN/godot/index.md"]
+      },
+      "ai_libs": {
+        "paths": [
+          "ai-libs/CoreGrid/project.godot",
+          "ai-libs/CoreGrid/global",
+          "ai-libs/CoreGrid/scenes"
+        ],
+        "search_hints": [
+          "rg -n \"GetNode|BindNodeSignal|AutoRegisterExported|project\\.godot|AutoLoad\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Godot.SourceGenerators.Abstractions": {
+      "aliases": [
+        "godot.sourcegenerators.abstractions",
+        "godot-source-generators-abstractions",
+        "godot source generators abstractions"
+      ],
+      "source_paths": ["GFramework.Godot.SourceGenerators.Abstractions"],
+      "project_file": "GFramework.Godot.SourceGenerators.Abstractions/GFramework.Godot.SourceGenerators.Abstractions.csproj",
+      "test_projects": ["GFramework.Godot.SourceGenerators.Tests/GFramework.Godot.SourceGenerators.Tests.csproj"],
+      "readme_paths": [],
+      "docs": {
+        "landing": ["docs/zh-CN/source-generators/index.md"],
+        "topics": [
+          "docs/zh-CN/source-generators/godot-project-generator.md",
+          "docs/zh-CN/source-generators/get-node-generator.md",
+          "docs/zh-CN/source-generators/bind-node-signal-generator.md"
+        ],
+        "fallback": ["docs/zh-CN/godot/index.md"]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/project.godot", "ai-libs/CoreGrid/global"],
+        "search_hints": [
+          "rg -n \"GFramework\\.Godot\\.SourceGenerators\\.Abstractions|GetNode|BindNodeSignal\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Cqrs": {
+      "aliases": ["cqrs", "mediator", "cqrs module"],
+      "source_paths": ["GFramework.Cqrs"],
+      "project_file": "GFramework.Cqrs/GFramework.Cqrs.csproj",
+      "test_projects": ["GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj"],
+      "readme_paths": ["GFramework.Cqrs/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/core/cqrs.md"],
+        "topics": [
+          "docs/zh-CN/core/command.md",
+          "docs/zh-CN/core/query.md",
+          "docs/zh-CN/core/cqrs.md"
+        ],
+        "fallback": [
+          "docs/zh-CN/core/index.md",
+          "docs/zh-CN/api-reference/index.md"
+        ]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/global", "ai-libs/CoreGrid/scripts"],
+        "search_hints": [
+          "rg -n \"CommandHandler|QueryHandler|RegisterCqrs|PipelineBehavior\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Cqrs.Abstractions": {
+      "aliases": ["cqrs.abstractions", "cqrs-abstractions", "cqrs abstractions"],
+      "source_paths": ["GFramework.Cqrs.Abstractions"],
+      "project_file": "GFramework.Cqrs.Abstractions/GFramework.Cqrs.Abstractions.csproj",
+      "test_projects": ["GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj"],
+      "readme_paths": ["GFramework.Cqrs.Abstractions/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/core/cqrs.md"],
+        "topics": [
+          "docs/zh-CN/core/command.md",
+          "docs/zh-CN/core/query.md"
+        ],
+        "fallback": ["docs/zh-CN/api-reference/index.md"]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/global"],
+        "search_hints": [
+          "rg -n \"GFramework\\.Cqrs\\.Abstractions|ICommand|IQuery|IRequest\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Cqrs.SourceGenerators": {
+      "aliases": [
+        "cqrs.sourcegenerators",
+        "cqrs-source-generators",
+        "cqrs source generators"
+      ],
+      "source_paths": ["GFramework.Cqrs.SourceGenerators"],
+      "project_file": "GFramework.Cqrs.SourceGenerators/GFramework.Cqrs.SourceGenerators.csproj",
+      "test_projects": ["GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj"],
+      "readme_paths": ["GFramework.Cqrs.SourceGenerators/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/source-generators/index.md"],
+        "topics": [],
+        "fallback": [
+          "docs/zh-CN/core/cqrs.md",
+          "docs/zh-CN/api-reference/index.md"
+        ]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/global"],
+        "search_hints": [
+          "rg -n \"GFramework\\.Cqrs\\.SourceGenerators|RequestHandler|PipelineBehavior\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Ecs.Arch": {
+      "aliases": ["ecs.arch", "ecs-arch", "ecs arch", "ecs"],
+      "source_paths": ["GFramework.Ecs.Arch"],
+      "project_file": "GFramework.Ecs.Arch/GFramework.Ecs.Arch.csproj",
+      "test_projects": ["GFramework.Ecs.Arch.Tests/GFramework.Ecs.Arch.Tests.csproj"],
+      "readme_paths": ["GFramework.Ecs.Arch/README.md"],
+      "docs": {
+        "landing": ["docs/zh-CN/ecs/index.md"],
+        "topics": ["docs/zh-CN/ecs/arch.md"],
+        "fallback": [
+          "docs/zh-CN/core/index.md",
+          "docs/zh-CN/api-reference/index.md"
+        ]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/scripts", "ai-libs/CoreGrid/global"],
+        "search_hints": [
+          "rg -n \"Arch\\.Core|World|SystemGroup|QueryDescription\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "Ecs.Arch.Abstractions": {
+      "aliases": [
+        "ecs.arch.abstractions",
+        "ecs-arch-abstractions",
+        "ecs arch abstractions"
+      ],
+      "source_paths": ["GFramework.Ecs.Arch.Abstractions"],
+      "project_file": "GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj",
+      "test_projects": ["GFramework.Ecs.Arch.Tests/GFramework.Ecs.Arch.Tests.csproj"],
+      "readme_paths": [],
+      "docs": {
+        "landing": ["docs/zh-CN/ecs/index.md"],
+        "topics": ["docs/zh-CN/ecs/arch.md"],
+        "fallback": ["docs/zh-CN/api-reference/index.md"]
+      },
+      "ai_libs": {
+        "paths": ["ai-libs/CoreGrid/scripts"],
+        "search_hints": [
+          "rg -n \"GFramework\\.Ecs\\.Arch\\.Abstractions|IArchSystem|IArchModel\" ai-libs/CoreGrid"
+        ]
+      }
+    },
+    "SourceGenerators.Common": {
+      "aliases": [
+        "sourcegenerators.common",
+        "source-generators-common",
+        "source generators common"
+      ],
+      "source_paths": ["GFramework.SourceGenerators.Common"],
+      "project_file": "GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj",
+      "test_projects": ["GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj"],
+      "readme_paths": [],
+      "docs": {
+        "landing": ["docs/zh-CN/source-generators/index.md"],
+        "topics": [],
+        "fallback": ["docs/zh-CN/api-reference/index.md"]
+      },
+      "ai_libs": {
+        "paths": [],
+        "search_hints": []
+      }
+    }
+  },
+  "docs_section_aliases": {
+    "core": ["Core"],
+    "abstractions": ["Core.Abstractions", "Game.Abstractions", "Ecs.Arch.Abstractions"],
+    "game": ["Game"],
+    "godot": ["Godot"],
+    "cqrs": ["Cqrs"],
+    "ecs": ["Ecs.Arch"],
+    "source-generators": [
+      "Core.SourceGenerators",
+      "Game.SourceGenerators",
+      "Cqrs.SourceGenerators",
+      "Godot.SourceGenerators"
+    ]
+  }
+}

.agents/skills/gframework-batch-boot/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: gframework-batch-boot
+description: Repository-specific bulk-task workflow for the GFramework repo. Use when Codex should start from the normal GFramework boot context and then continue a repetitive or large-scope task in automatic batches without waiting for manual round-by-round prompts, especially for analyzer warning cleanup, repetitive test refactors, documentation waves, or similar multi-file work with an explicit stop condition such as changed-file count, warning count, or timebox.
+---
+
+# GFramework Batch Boot
+
+## Overview
+
+Use this skill when `gframework-boot` is necessary but not sufficient because the task should keep advancing in bounded
+batches until a clear stop condition is met.
+
+Treat `AGENTS.md` as the source of truth. This skill extends `gframework-boot`; it does not replace it.
+
+## Startup Workflow
+
+1. Execute the normal `gframework-boot` startup sequence first:
+   - read `AGENTS.md`
+   - read `.ai/environment/tools.ai.yaml`
+   - read `ai-plan/public/README.md`
+   - read the mapped active topic `todos/` and `traces/`
+2. Classify the task as a batch candidate only if all of the following are true:
+   - the work is repetitive, sliceable, or likely to require multiple similar iterations
+   - each batch can be given an explicit ownership boundary
+   - a stop condition can be measured locally
+3. Before any delegation, define the batch objective in one sentence:
+   - warning family reduction
+   - repeated test refactor pattern
+   - module-by-module documentation refresh
+   - other repetitive multi-file cleanup
+
+## Baseline Selection
+
+When the stop condition depends on branch size or changed-file count, choose the baseline carefully.
+
+1. Prefer the freshest remote-tracking reference that already exists locally:
+   - `origin/main`
+   - or the mapped upstream base branch for the current topic
+2. Do not default to local `main` when `refs/heads/main` is behind `refs/remotes/origin/main`.
+3. If both local and remote-tracking refs exist, report:
+   - ref name
+   - short SHA
+   - committer date
+4. If only a local branch exists, state that the baseline may be stale before using it.
+5. When the task is tied to a PR or topic branch rather than `main`, prefer that explicit upstream comparison target over
+   a generic `main`.
+
+For changed-file limits, measure branch-wide scope against the chosen baseline, not just the current working tree:
+
+- use `git diff --name-only <baseline>...HEAD`
+- do not confuse branch diff size with `git status --short`
+
+For changed-line limits, also measure branch-wide scope against the chosen baseline:
+
+- prefer `git diff --numstat <baseline>...HEAD`
+- treat "changed lines" as `added + deleted` summed across the branch diff
+- do not use working-tree-only line counts as a substitute for branch-wide scope
+
+For shorthand numeric thresholds, use a fixed default baseline:
+
+- compare the current branch's cumulative diff against remote `origin/main`
+- include all commits reachable from `HEAD` that are not already in `origin/main`
+- do not reinterpret shorthand thresholds as "this batch only" or "current unstaged changes only"
+- only use another baseline when the user explicitly names it in the prompt
+
+## Stop Conditions
+
+Choose one primary stop condition before the first batch and restate it to the user.
+
+Common stop conditions:
+
+- branch diff vs baseline approaches a file-count threshold
+- warnings-only build reaches a target count
+- a specific hotspot list is exhausted
+- a timebox or validation budget is reached
+
+If multiple stop conditions exist, rank them and treat one as primary.
+
+## Shorthand Stop-Condition Syntax
+
+`gframework-batch-boot` may be invoked with shorthand numeric thresholds when the user clearly wants a branch-size stop
+condition instead of a long natural-language prompt.
+
+Interpret shorthand as follows:
+
+- `$gframework-batch-boot 75`
+  - means: stop when the current branch's cumulative diff vs remote `origin/main` approaches `75` changed files
+- `$gframework-batch-boot 75 2000`
+  - means: stop when the current branch's cumulative diff vs remote `origin/main` approaches `75` changed files OR
+    `2000` changed lines
+  - default positional meaning is `<files> <lines>`
+- `$gframework-batch-boot 75 | 2000`
+  - may be interpreted as the same OR shorthand in plain-language chat
+  - when restating, planning, or documenting the command, normalize it to `$gframework-batch-boot 75 2000`
+  - prefer the no-pipe form because `|` is easy to confuse with a shell pipeline
+
+When shorthand is used:
+
+- report the resolved thresholds explicitly before the first batch
+- report that the baseline is remote `origin/main`, unless the user explicitly overrides it
+- if two numeric thresholds are present, treat file count as the default primary metric for status reporting unless the
+  user says otherwise
+- stop when either threshold is reached or exceeded, even if the other threshold still has headroom
+
+## Batch Loop
+
+1. Inspect the current state before the first batch:
+   - current branch and active topic
+   - selected baseline
+   - current stop-condition metric
+   - next candidate slices
+2. Keep the critical path local.
+3. Delegate only bounded slices with explicit ownership:
+   - one file
+   - one warning family within one project
+   - one module documentation wave
+4. For each worker batch, specify:
+   - objective
+   - owned files or subsystem
+   - required validation commands
+   - output format
+   - reminder that other agents may be editing the repo
+5. While workers run, use the main thread for non-overlapping tasks:
+   - queue the next candidate slice
+   - inspect the next hotspot
+   - recompute branch size or warning distribution
+6. After each completed batch:
+   - integrate or verify the result
+   - rerun the required validation
+   - recompute the primary stop-condition metric
+   - decide immediately whether to continue or stop
+7. Do not require the user to manually trigger every round unless:
+   - the next slice is ambiguous
+   - a validation failure changes strategy
+   - the batch objective conflicts with the active topic
+
+## Task Tracking
+
+For multi-batch work, keep recovery artifacts current.
+
+- Update the active `ai-plan/public/<topic>/todos/` document when a meaningful batch lands.
+- Update the matching `traces/` document with:
+  - accepted delegated scope
+  - validation milestones
+  - current stop-condition metric
+  - next recommended batch
+- Keep the active recovery point concise; archive detailed history when it starts to sprawl.
+
+## Delegation Defaults
+
+- Prefer `worker` subagents for independent write slices.
+- Prefer `explorer` subagents for read-only hotspot ranking or next-batch discovery.
+- Keep each worker ownership boundary disjoint.
+- Avoid launching a new batch when the expected write set would push the branch beyond the declared threshold without a
+  deliberate decision.
+
+## Completion
+
+Stop the loop when any of the following becomes true:
+
+- the primary stop condition has been reached or exceeded
+- the remaining slices are no longer low-risk
+- validation failures indicate the task is no longer repetitive
+- the branch has grown large enough that reviewability would materially degrade
+
+When stopping, report:
+
+- which baseline was used
+- the exact metric value at stop time
+- completed batches
+- remaining candidate batches
+- whether further work should continue in a new turn or after rebasing/fetching
+
+## 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.`

.agents/skills/gframework-batch-boot/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GFramework Batch Boot"
+  short_description: "Run boot, then iterate bounded bulk batches"
+  default_prompt: "Use $gframework-batch-boot to start from the normal GFramework boot context and continue the current repetitive task in automatic bounded batches until the declared stop condition is reached."

.agents/skills/gframework-boot/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gframework-boot
+description: Repository-specific boot workflow for the GFramework repo. Use when Codex needs to start or resume work in this repository from short prompts such as "boot", "continue", "read AGENTS", or "start the next step"; when the user expects Codex to first read AGENTS.md, .ai/environment/tools.ai.yaml, and public ai-plan tracking files; or when Codex should assess task complexity, decide whether explorer or worker subagents are warranted, and then proceed under the repository's workflow rules.
+---
+
+# GFramework Boot
+
+## Overview
+
+Use this skill to bootstrap work in the GFramework repository with minimal user prompting.
+Treat `AGENTS.md` as the source of truth. Use this skill to enforce a startup sequence, not to replace repository rules.
+
+## Startup Workflow
+
+1. Read `AGENTS.md` before choosing tools, planning edits, or delegating work.
+2. Read `.ai/environment/tools.ai.yaml` to confirm the preferred local toolchain.
+3. Read `ai-plan/public/README.md` before asking the user for missing context.
+4. If `ai-plan/public/README.md` maps the current branch or worktree to active topics, inspect those topics'
+   `todos/` and `traces/` directories in listed priority order.
+5. If no mapping exists, scan `ai-plan/public/<topic>/todos/` and `ai-plan/public/<topic>/traces/` across active
+   topics, and ignore `ai-plan/public/archive/` unless the user explicitly asks for historical context.
+6. Treat `ai-plan/public/<topic>/archive/` as secondary context even for active topics; only read it when the active
+   todo/trace files point there or when the user explicitly asks for historical detail.
+7. If `ai-plan/private/<branch-or-worktree>/` exists and is relevant, treat it as private recovery context for the
+   current worktree only and do not assume it should be committed.
+8. Classify the task state:
+   - `new`: no matching recovery document exists, or the user is clearly starting fresh work
+   - `resume`: a matching todo or trace exists and the user is continuing that thread
+   - `recovery`: prior work looks partial, interrupted, or ambiguous and the next safe recovery point must be reconstructed
+9. Choose the best matching `ai-plan` artifacts:
+   - Prefer topics explicitly mapped from `ai-plan/public/README.md`
+   - Prefer path names or headings that match the user's task wording
+   - Break ties by most recently updated trace or todo
+   - If ambiguity would materially change implementation, summarize the candidates and ask one concise question
+10. Classify the task complexity before deciding on subagents:
+   - `simple`: one concern, one file or module, no parallel discovery required
+   - `medium`: a small number of modules, some read-only exploration helpful, critical path still easy to keep local
+   - `complex`: cross-module design, migration, large refactor, or work likely to exceed one context window
+11. Apply the delegation policy from `AGENTS.md`:
+   - Keep the critical path local
+   - Use `explorer` with `gpt-5.1-codex-mini` for narrow read-only questions, tracing, inventory, and comparisons
+   - Use `worker` with `gpt-5.4` only for bounded implementation tasks with explicit ownership
+   - Do not delegate purely for ceremony; delegate only when it materially shortens the task or controls context growth
+12. Before editing files, tell the user what you read, how you classified the task, whether subagents will be used,
+    and the first implementation step.
+13. Proceed with execution, validation, and documentation updates required by `AGENTS.md`.
+
+## Task Tracking
+
+For multi-step, cross-module, or interruption-prone work, maintain the repository recovery artifacts instead of keeping state only in chat.
+
+- Update `ai-plan/public/README.md` whenever the active topic set or worktree mapping changes.
+- Update the active public document under `ai-plan/public/<topic>/todos/` with completed work, validation results,
+  risks, and the next recovery point.
+- Update the matching public trace under `ai-plan/public/<topic>/traces/` with key decisions, delegated scope, and the
+  immediate next step.
+- Keep the active todo/trace files concise enough for `boot` to use as default entrypoints. When completed, validated
+  stages start piling up, move their detailed history into `ai-plan/public/<topic>/archive/` and leave archive
+  pointers in the active files.
+- Move stage-complete artifacts into `ai-plan/public/<topic>/archive/`, and move completed topics into
+  `ai-plan/public/archive/<topic>/` so `boot` does not keep reloading stale context.
+- Keep worktree-private scratch recovery files under `ai-plan/private/` and do not treat them as commit targets.
+- Never write secrets, machine-specific paths, or other sensitive environment details into any `ai-plan/**` artifact.
+- If the task is clearly complex and no recovery artifact exists yet, create one before substantive edits.
+
+## Recovery Heuristics
+
+- If the user says `next step`, `continue`, `继续`, or similar resume language, read `ai-plan/public/README.md`
+  first, then search the mapped active topics before scanning the broader public area.
+- If the current branch and the mapped active topics describe the same feature area, prefer resuming those topics first.
+- If the repository state suggests in-flight work but no recovery document matches, reconstruct the safest next step from code, tests, and Git state before asking the user for clarification.
+
+## Example Triggers
+
+- `boot`
+- `Use $gframework-boot and continue the current task`
+- `Read AGENTS and public ai-plan, then start the next step`
+- `继续当前任务，先看 AGENTS.md 和 public ai-plan`
+
+## References
+
+Read `references/startup-artifacts.md` when you need a quick reminder of the repository entrypoints, task-state heuristics, or delegation defaults without re-reading the entire skill.

.agents/skills/gframework-boot/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GFramework Boot"
+  short_description: "Bootstrap GFramework repository tasks"
+  default_prompt: "Use $gframework-boot to start or resume work in this GFramework repository."

.agents/skills/gframework-boot/references/startup-artifacts.md

@@ -0,0 +1,38 @@
+# Startup Artifacts
+
+## Required Reads
+
+- `AGENTS.md`
+- `.ai/environment/tools.ai.yaml`
+- `ai-plan/public/README.md`
+- the selected `ai-plan/public/<topic>/todos/` directories
+- the selected `ai-plan/public/<topic>/traces/` directories
+
+## AI-Plan Selection Heuristics
+
+- Match the current branch or worktree against `ai-plan/public/README.md` first.
+- If the index maps the current worktree to topics, inspect those topics in listed order before scanning anything else.
+- Match the user's wording against public todo and trace file names next.
+- Prefer the newest matching trace when several candidates describe the same feature area.
+- If one file records a clearer recovery point than a newer but vague file, prefer the clearer recovery point.
+- Ignore `ai-plan/public/archive/**` unless the user explicitly requests historical recovery context.
+- Even inside an active topic, prefer the root `todos/` and `traces/` entry files first; only read `archive/` when the
+  active files point there or when the user asks for historical detail.
+- If a matching `ai-plan/private/<branch-or-worktree>/` directory exists, use it only as private context for the current worktree.
+
+## Complexity Defaults
+
+- `simple`: keep everything local, no subagent
+- `medium`: keep design local, optionally use one `explorer` for parallel read-only discovery
+- `complex`: keep architecture and integration local, delegate only bounded non-blocking subtasks
+
+## Model Defaults
+
+- `explorer`: `gpt-5.1-codex-mini`
+- `worker`: `gpt-5.4`
+
+## Startup Summary Template
+
+Use a short update before execution:
+
+`Read AGENTS.md, the environment inventory, ai-plan/public/README.md, and the relevant public ai-plan artifacts. This looks like a <task-state> <complexity> task. I will <delegate-or-not> and start with <first-step>.`

.agents/skills/gframework-doc-refresh/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: gframework-doc-refresh
+description: "Refresh or reassess GFramework documentation for a source module such as Core, Game, Godot, Cqrs, Ecs.Arch, or their generator/abstraction packages. Use this when the user asks to update module docs, re-evaluate landing pages, fix outdated topic pages, refresh API reference coverage, verify adoption paths against source/tests/README, or compare current docs with ai-libs consumer wiring. Recommended command: /gframework-doc-refresh <module>."
+---
+
+# Purpose
+
+Use this skill to refresh GFramework documentation from source-first evidence.
+
+The public entry is module-driven, not doc-type-driven:
+
+- Input: a source module or a resolvable docs section alias
+- Output: the minimal documentation update set needed for that module
+- Evidence: code, tests, README, current docs, then `ai-libs/`
+
+Do not start by deciding “this is an API doc task” or “this is a tutorial task”.
+Decide that only after the module scan.
+
+# Triggers
+
+Use this skill when the user asks things like:
+
+- `refresh docs for Core`
+- `update Game module docs`
+- `根据 Godot 模块源码刷新文档`
+- `重新评估 Cqrs 模块文档并更新`
+- `核对 Godot.SourceGenerators 的文档状态`
+- `看看 source-generators 栏目哪些页面已经失真`
+
+Recommended command form:
+
+```bash
+/gframework-doc-refresh <module>
+```
+
+# Supported Modules
+
+Canonical module names:
+
+- `Core`
+- `Core.Abstractions`
+- `Core.SourceGenerators`
+- `Core.SourceGenerators.Abstractions`
+- `Game`
+- `Game.Abstractions`
+- `Game.SourceGenerators`
+- `Godot`
+- `Godot.SourceGenerators`
+- `Godot.SourceGenerators.Abstractions`
+- `Cqrs`
+- `Cqrs.Abstractions`
+- `Cqrs.SourceGenerators`
+- `Ecs.Arch`
+- `Ecs.Arch.Abstractions`
+- `SourceGenerators.Common`
+
+The canonical mapping lives in `.agents/skills/_shared/module-map.json`.
+
+If the user supplies a docs section name:
+
+- resolve it back to a source module first
+- if it maps to multiple modules, stop at normalization guidance and do not draft docs yet
+
+# Workflow
+
+## 1. Normalize the input
+
+Run:
+
+```bash
+python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py <module>
+```
+
+The script normalizes aliases, reports ambiguity, and prints the module's evidence surface.
+
+If the result is ambiguous:
+
+- return the candidate modules
+- ask the user to pick the intended source module
+- do not continue into document generation
+
+## 2. Scan the evidence surface
+
+For the resolved module, inspect:
+
+- source directories
+- `*.csproj`
+- relevant test projects
+- sibling `README.md`
+- mapped `docs/zh-CN` landing pages and topic pages
+- optional `ai-libs/` consumer evidence when needed
+
+Always confirm the actual files in the repository.
+Do not assume the mapping is enough on its own.
+
+## 3. Decide whether `ai-libs/` is needed
+
+Use `ai-libs/` when:
+
+- adoption path is unclear from source and README alone
+- extension points need a real consumer wiring example
+- current docs have concepts but lack an end-to-end integration path
+
+Do not rely on `ai-libs/` for:
+
+- public API contract definitions
+- generator diagnostics or semantic guarantees
+- claims about what the current version officially supports
+
+If `ai-libs/` conflicts with current source or tests, keep source/tests as the contract and document the migration boundary.
+
+## 4. Judge the documentation state
+
+Classify the module into one or more of these states:
+
+- missing landing page
+- stale landing page
+- stale topic page
+- missing or stale API reference coverage
+- stale tutorial/example
+- validation-only
+
+Base this on evidence, not on the previous docs shape.
+
+## 5. Choose the output set
+
+Always prioritize:
+
+1. README / landing page / adoption path
+2. topic pages
+3. API reference
+4. tutorials
+
+If the module only needs validation or relinking, do not generate extra pages.
+
+## 6. Draft or update docs
+
+Load only the template that matches the output you selected:
+
+- `templates/module-landing.md`
+- `templates/topic-refresh.md`
+- `templates/api-reference.md`
+- `templates/tutorial.md`
+
+Keep examples minimal, current, and traceable to source or tests.
+
+## 7. Validate
+
+Run the internal validators as needed:
+
+```bash
+bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh <file-or-directory>
+```
+
+For site-level confirmation after doc edits:
+
+```bash
+cd docs && bun run build
+```
+
+# Evidence Order
+
+Use this exact priority:
+
+1. source code, XML docs, `*.csproj`
+2. tests and snapshots
+3. module `README.md`
+4. current `docs/zh-CN` pages
+5. verified `ai-libs/` consumers
+6. archived docs only as fallback context
+
+# Output Rules
+
+- Prefer correcting the adoption path over expanding page count.
+- Do not copy wording from outdated docs just to keep page volume.
+- Public docs must stay reader-facing. Do not write inventory, coverage baseline, recovery-point, batch-metric, review
+  backlog, or audit-wave wording into `README.md` or `docs/**`.
+- Use neutral, destination-first section names and link labels. Do not expose raw filenames or paths such as
+  `game/index.md`, `README.md`, or `../core/cqrs.md` as visible reader-facing labels when a semantic label is
+  available.
+- Do not use rhetorical or conversational headings in public docs, such as “你真正会用到的公开入口”、
+  “先理解包关系” or “想看……转到……”. Prefer direct labels such as “公开入口”、
+  “模块与包关系” and “相关主题”.
+- Keep public docs out of internal product-decision tone. Do not publish repository-governance wording such as
+  “当前阶段的结论”、“不建议立即启动” or audience-maintainer tradeoff discussions unless the page itself is a public
+  adoption guide and the wording has been rewritten as reader-facing suitability guidance.
+- If XML or audit evidence is relevant, translate it into reader guidance such as “which types to inspect first” or
+  “which entry points define the contract”, instead of exposing counts, dates, or governance status.
+- Escape generics outside code blocks.
+- Keep internal links real and current.
+- Mark code blocks with explicit languages.
+- Use the smallest example that demonstrates the current contract.
+- Consumer examples may align with `ai-libs/`, but must not exceed the current module contract.
+
+# Validation
+
+Use the shared standards in `.agents/skills/_shared/DOCUMENTATION_STANDARDS.md`.
+
+When this skill changes public docs, prefer:
+
+1. focused validator on touched pages
+2. `cd docs && bun run build`
+
+When this skill changes the skill system itself:
+
+1. validate `SKILL.md` frontmatter exists
+2. run the module scan script for representative modules
+3. confirm obsolete `vitepress-*` public entries are gone
+
+# References
+
+Read these only when needed:
+
+- `.agents/skills/_shared/DOCUMENTATION_STANDARDS.md`
+- `.agents/skills/_shared/module-map.json`
+- `references/module-selection.md`
+- `references/evidence-and-ai-libs.md`
+- `references/output-strategy.md`

.agents/skills/gframework-doc-refresh/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GFramework Doc Refresh"
+  short_description: "Refresh module docs from code-first evidence"
+  default_prompt: "Use $gframework-doc-refresh to refresh a GFramework module's docs from source, tests, README, current docs, and ai-libs evidence."

.agents/skills/gframework-doc-refresh/references/evidence-and-ai-libs.md

@@ -0,0 +1,35 @@
+# Evidence And `ai-libs`
+
+The evidence order is fixed:
+
+1. source code, XML docs, `*.csproj`
+2. tests and snapshots
+3. module README
+4. current `docs/zh-CN`
+5. `ai-libs/`
+6. archived docs
+
+## When To Use `ai-libs`
+
+Use `ai-libs/` to answer questions like:
+
+- How is this extension point wired in a real project?
+- What does the minimal project layout look like?
+- Which project-side files need to exist for this module to work end to end?
+
+## When Not To Use `ai-libs`
+
+Do not use `ai-libs/` as the primary source for:
+
+- public API semantics
+- exact generator output guarantees
+- supported package matrix
+- diagnostics behavior
+
+## Conflict Rule
+
+If `ai-libs/` drifts from the current repo:
+
+- trust source and tests
+- mention the drift as a compatibility or migration note
+- do not document old consumer behavior as if it were still the contract

.agents/skills/gframework-doc-refresh/references/module-selection.md

@@ -0,0 +1,29 @@
+# Module Selection
+
+Use `.agents/skills/_shared/module-map.json` as the canonical source for:
+
+- supported modules
+- aliases
+- source paths
+- test projects
+- README paths
+- docs landing/topic/fallback pages
+- `ai-libs/` reference roots
+
+Selection rules:
+
+1. Prefer explicit canonical module names.
+2. Resolve docs section aliases back to source modules before scanning docs.
+3. If an alias maps to multiple modules, stop and return the candidate list.
+4. If a module has no dedicated docs section, fall back to the nearest existing landing page or API index instead of inventing a fake section.
+
+Representative ambiguous inputs:
+
+- `source-generators` -> likely one of `Core.SourceGenerators`, `Game.SourceGenerators`, `Cqrs.SourceGenerators`, `Godot.SourceGenerators`
+- `abstractions` -> likely one of `Core.Abstractions`, `Game.Abstractions`, `Ecs.Arch.Abstractions`
+
+Representative resolvable aliases:
+
+- `core-abstractions` -> `Core.Abstractions`
+- `godot generators` -> `Godot.SourceGenerators`
+- `ecs` -> `Ecs.Arch`

.agents/skills/gframework-doc-refresh/references/output-strategy.md

@@ -0,0 +1,38 @@
+# Output Strategy
+
+The module scan determines the document type.
+
+Use this priority:
+
+1. fix README / landing page / adoption path
+2. fix stale topic pages
+3. add or refresh API reference coverage
+4. add or refresh tutorials
+
+## Landing Page Checklist
+
+- module purpose
+- package relationship
+- minimum adoption path
+- real entry points
+- next-reading links
+
+## Topic Page Checklist
+
+- current role
+- public entry points
+- minimum example
+- compatibility or migration boundary
+- related pages
+
+## API Reference Checklist
+
+- only for types or members that materially help consumers
+- grounded in XML docs and source
+- no speculative examples
+
+## Tutorial Checklist
+
+- only after the landing path is accurate
+- keep the scenario traceable to source/tests or `ai-libs/`
+- explain why each step exists, not just the code shape

.agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Normalize a GFramework docs module input and report its evidence surface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+REPO_ROOT = SCRIPT_DIR.parents[3]
+MODULE_MAP_PATH = REPO_ROOT / ".agents/skills/_shared/module-map.json"
+
+
+def load_module_map() -> dict[str, Any]:
+    return json.loads(MODULE_MAP_PATH.read_text(encoding="utf-8"))
+
+
+def normalize_key(value: str) -> str:
+    return value.strip().lower().replace("_", "-").replace(" ", "-")
+
+
+def resolve_module(raw_input: str, module_map: dict[str, Any]) -> dict[str, Any]:
+    modules = module_map["modules"]
+    docs_section_aliases = module_map.get("docs_section_aliases", {})
+    normalized = normalize_key(raw_input)
+
+    for canonical_name in modules:
+        if normalize_key(canonical_name) == normalized:
+            return {"status": "ok", "module": canonical_name, "reason": "canonical"}
+
+    for canonical_name, config in modules.items():
+        aliases = config.get("aliases", [])
+        if normalized in {normalize_key(alias) for alias in aliases}:
+            return {"status": "ok", "module": canonical_name, "reason": "alias"}
+
+    if normalized in docs_section_aliases:
+        candidates = docs_section_aliases[normalized]
+        if len(candidates) == 1:
+            return {"status": "ok", "module": candidates[0], "reason": "docs_section"}
+        return {
+            "status": "ambiguous",
+            "reason": "docs_section",
+            "input": raw_input,
+            "candidates": candidates,
+        }
+
+    fuzzy = [
+        canonical_name
+        for canonical_name in modules
+        if normalized in normalize_key(canonical_name) or normalize_key(canonical_name) in normalized
+    ]
+    if fuzzy:
+        return {"status": "unknown", "reason": "closest_match", "input": raw_input, "candidates": fuzzy}
+
+    return {"status": "unknown", "reason": "no_match", "input": raw_input, "candidates": []}
+
+
+def collect_path_state(paths: list[str]) -> list[dict[str, Any]]:
+    states: list[dict[str, Any]] = []
+    for relative_path in paths:
+        absolute_path = REPO_ROOT / relative_path
+        states.append(
+            {
+                "path": relative_path,
+                "exists": absolute_path.exists(),
+                "kind": "dir" if absolute_path.is_dir() else "file",
+            }
+        )
+    return states
+
+
+def assess_docs(module_config: dict[str, Any]) -> list[str]:
+    docs_config = module_config["docs"]
+    landing = collect_path_state(docs_config.get("landing", []))
+    topics = collect_path_state(docs_config.get("topics", []))
+    assessment: list[str] = []
+
+    if landing and not any(item["exists"] for item in landing):
+        assessment.append("landing_missing")
+    elif landing:
+        assessment.append("landing_present")
+
+    if not topics:
+        assessment.append("topic_docs_not_mapped")
+    else:
+        existing_topics = sum(1 for item in topics if item["exists"])
+        if existing_topics == 0:
+            assessment.append("topic_docs_missing")
+        elif existing_topics < len(topics):
+            assessment.append("topic_docs_partial")
+        else:
+            assessment.append("topic_docs_present")
+
+    return assessment
+
+
+def build_report(module_name: str, module_config: dict[str, Any]) -> dict[str, Any]:
+    source_paths = collect_path_state(module_config.get("source_paths", []))
+    test_projects = collect_path_state(module_config.get("test_projects", []))
+    readmes = collect_path_state(module_config.get("readme_paths", []))
+    docs_config = module_config["docs"]
+    ai_libs = module_config.get("ai_libs", {})
+
+    report = {
+        "status": "ok",
+        "module": module_name,
+        "source_paths": source_paths,
+        "project_file": collect_path_state([module_config["project_file"]])[0],
+        "test_projects": test_projects,
+        "readme_paths": readmes,
+        "docs": {
+          "landing": collect_path_state(docs_config.get("landing", [])),
+          "topics": collect_path_state(docs_config.get("topics", [])),
+          "fallback": collect_path_state(docs_config.get("fallback", []))
+        },
+        "ai_libs": {
+            "paths": collect_path_state(ai_libs.get("paths", [])),
+            "search_hints": ai_libs.get("search_hints", []),
+        },
+        "assessment": assess_docs(module_config),
+    }
+
+    if readmes and not any(item["exists"] for item in readmes):
+        report["assessment"].append("readme_missing")
+
+    if test_projects and not any(item["exists"] for item in test_projects):
+        report["assessment"].append("tests_missing")
+
+    if not ai_libs.get("paths"):
+        report["assessment"].append("ai_libs_optional")
+
+    if not docs_config.get("topics"):
+        report["assessment"].append("fallback_docs_only")
+
+    return report
+
+
+def print_text_report(report: dict[str, Any]) -> None:
+    if report["status"] != "ok":
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return
+
+    print(f"module: {report['module']}")
+    print("assessment:")
+    for item in report["assessment"]:
+        print(f"  - {item}")
+
+    print("source:")
+    for item in report["source_paths"]:
+        print(f"  - {'OK' if item['exists'] else 'MISS'} {item['path']}")
+
+    project_file = report["project_file"]
+    print(f"project: {'OK' if project_file['exists'] else 'MISS'} {project_file['path']}")
+
+    print("tests:")
+    for item in report["test_projects"]:
+        print(f"  - {'OK' if item['exists'] else 'MISS'} {item['path']}")
+
+    print("readme:")
+    if report["readme_paths"]:
+        for item in report["readme_paths"]:
+            print(f"  - {'OK' if item['exists'] else 'MISS'} {item['path']}")
+    else:
+        print("  - none mapped")
+
+    print("docs landing:")
+    for item in report["docs"]["landing"]:
+        print(f"  - {'OK' if item['exists'] else 'MISS'} {item['path']}")
+
+    print("docs topics:")
+    if report["docs"]["topics"]:
+        for item in report["docs"]["topics"]:
+            print(f"  - {'OK' if item['exists'] else 'MISS'} {item['path']}")
+    else:
+        print("  - none mapped")
+
+    print("docs fallback:")
+    for item in report["docs"]["fallback"]:
+        print(f"  - {'OK' if item['exists'] else 'MISS'} {item['path']}")
+
+    print("ai-libs:")
+    if report["ai_libs"]["paths"]:
+        for item in report["ai_libs"]["paths"]:
+            print(f"  - {'OK' if item['exists'] else 'MISS'} {item['path']}")
+    else:
+        print("  - none mapped")
+
+    if report["ai_libs"]["search_hints"]:
+        print("ai-libs search hints:")
+        for item in report["ai_libs"]["search_hints"]:
+            print(f"  - {item}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("module", help="Canonical module name, alias, or docs section name.")
+    parser.add_argument("--json", action="store_true", help="Emit JSON instead of text.")
+    args = parser.parse_args()
+
+    module_map = load_module_map()
+    resolution = resolve_module(args.module, module_map)
+
+    if resolution["status"] != "ok":
+        if args.json:
+            print(json.dumps(resolution, ensure_ascii=False, indent=2))
+        else:
+            print(json.dumps(resolution, ensure_ascii=False, indent=2))
+        return 1
+
+    report = build_report(resolution["module"], module_map["modules"][resolution["module"]])
+    report["resolution"] = resolution
+
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        print_text_report(report)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.agents/skills/gframework-doc-refresh/scripts/validate-all.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# 运行统一文档校验脚本集合。
+
+set -e
+
+TARGET="$1"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [ -z "$TARGET" ]; then
+    echo "用法: $0 <文件或目录路径>"
+    exit 1
+fi
+
+if [ ! -e "$TARGET" ]; then
+    echo "错误: 路径不存在: $TARGET"
+    exit 1
+fi
+
+if [ -f "$TARGET" ]; then
+    FILES=("$TARGET")
+else
+    mapfile -t FILES < <(find "$TARGET" -type f -name "*.md" | sort)
+fi
+
+if [ ${#FILES[@]} -eq 0 ]; then
+    echo "未找到 Markdown 文件"
+    exit 0
+fi
+
+TOTAL_ERRORS=0
+FAILED_FILES=0
+
+for FILE in "${FILES[@]}"; do
+    FILE_ERRORS=0
+
+    echo "验证: $FILE"
+
+    if ! bash "$SCRIPT_DIR/validate-frontmatter.sh" "$FILE"; then
+        FILE_ERRORS=$((FILE_ERRORS + 1))
+    fi
+
+    if ! bash "$SCRIPT_DIR/validate-links.sh" "$FILE"; then
+        FILE_ERRORS=$((FILE_ERRORS + 1))
+    fi
+
+    if ! bash "$SCRIPT_DIR/validate-code-blocks.sh" "$FILE"; then
+        FILE_ERRORS=$((FILE_ERRORS + 1))
+    fi
+
+    if [ $FILE_ERRORS -eq 0 ]; then
+        echo "✓ $FILE"
+    else
+        echo "✗ $FILE"
+        FAILED_FILES=$((FAILED_FILES + 1))
+    fi
+
+    TOTAL_ERRORS=$((TOTAL_ERRORS + FILE_ERRORS))
+    echo ""
+done
+
+if [ $TOTAL_ERRORS -eq 0 ]; then
+    echo "✓ 所有验证通过"
+    exit 0
+fi
+
+echo "✗ 验证失败：$FAILED_FILES 个文件存在问题"
+exit 1

.agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# 验证 Markdown 代码块是否闭合并带有语言标记。
+
+set -e
+
+FILE="$1"
+
+if [ -z "$FILE" ]; then
+    echo "用法: $0 <文件路径>"
+    exit 1
+fi
+
+if [ ! -f "$FILE" ]; then
+    echo "错误: 文件不存在: $FILE"
+    exit 1
+fi
+
+ERROR_COUNT=0
+WARNING_COUNT=0
+CODE_FENCE_COUNT=$(grep -c '^```' "$FILE" || true)
+
+if [ $((CODE_FENCE_COUNT % 2)) -ne 0 ]; then
+    echo "✗ 错误: 存在未闭合的代码块"
+    ERROR_COUNT=$((ERROR_COUNT + 1))
+fi
+
+LINE_NUMBER=0
+IN_CODE_BLOCK=0
+while IFS= read -r LINE || [ -n "$LINE" ]; do
+    LINE_NUMBER=$((LINE_NUMBER + 1))
+
+    if [[ "$LINE" =~ ^\`\`\`(cs|c#|C#)$ ]]; then
+        echo "⚠ 警告: 第 $LINE_NUMBER 行使用了非标准 C# 标记，建议改为 csharp"
+        WARNING_COUNT=$((WARNING_COUNT + 1))
+    fi
+
+    if [[ "$LINE" =~ ^\`\`\` ]]; then
+        if [ "$IN_CODE_BLOCK" -eq 0 ]; then
+            if [[ "$LINE" == '```' ]]; then
+                echo "⚠ 警告: 第 $LINE_NUMBER 行的代码块缺少语言标记"
+                WARNING_COUNT=$((WARNING_COUNT + 1))
+            fi
+
+            IN_CODE_BLOCK=1
+        else
+            IN_CODE_BLOCK=0
+        fi
+    fi
+done < "$FILE"
+
+if [ $ERROR_COUNT -eq 0 ] && [ $WARNING_COUNT -eq 0 ]; then
+    echo "✓ 代码块验证通过"
+    exit 0
+fi
+
+if [ $ERROR_COUNT -eq 0 ]; then
+    echo "⚠ 代码块验证通过，但有 $WARNING_COUNT 个警告"
+    exit 0
+fi
+
+echo "✗ 代码块验证失败（$ERROR_COUNT 个错误，$WARNING_COUNT 个警告）"
+exit 1

.agents/skills/gframework-doc-refresh/scripts/validate-frontmatter.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# 验证 Markdown frontmatter。
+
+set -e
+
+FILE="$1"
+
+if [ -z "$FILE" ]; then
+    echo "用法: $0 <文件路径>"
+    exit 1
+fi
+
+if [ ! -f "$FILE" ]; then
+    echo "错误: 文件不存在: $FILE"
+    exit 1
+fi
+
+if ! head -n 5 "$FILE" | grep -q "^---$"; then
+    echo "✗ 错误: 文件缺少 frontmatter"
+    exit 1
+fi
+
+FRONTMATTER=$(sed -n '/^---$/,/^---$/p' "$FILE" | sed '1d;$d')
+
+if [ -z "$FRONTMATTER" ]; then
+    echo "✗ 错误: frontmatter 为空"
+    exit 1
+fi
+
+if ! echo "$FRONTMATTER" | grep -q "^title:"; then
+    echo "✗ 错误: 缺少必需字段: title"
+    exit 1
+fi
+
+if ! echo "$FRONTMATTER" | grep -q "^description:"; then
+    echo "✗ 错误: 缺少必需字段: description"
+    exit 1
+fi
+
+echo "✓ Frontmatter 验证通过"

.agents/skills/gframework-doc-refresh/scripts/validate-links.sh

@@ -1,11 +1,9 @@
 #!/bin/bash
-# 验证内部链接有效性
-# 用法: validate-links.sh <文件路径>
+# 验证 Markdown 内部链接是否指向当前仓库中的真实页面。
 
 set -e
 
 FILE="$1"
-BASE_DIR="docs/zh-CN"
 
 if [ -z "$FILE" ]; then
     echo "用法: $0 <文件路径>"
@@ -17,58 +15,40 @@ if [ ! -f "$FILE" ]; then
     exit 1
 fi
 
-echo "验证内部链接: $FILE"
-
-# 获取文件所在目录
 FILE_DIR=$(dirname "$FILE")
-
-# 提取所有 Markdown 链接
 LINKS=$(grep -oP '\[([^\]]+)\]\(([^)]+)\)' "$FILE" | grep -oP '\(([^)]+)\)' | sed 's/[()]//g' || true)
 
 if [ -z "$LINKS" ]; then
-    echo "✓ 未找到链接"
+    echo "✓ 未找到需要验证的链接"
     exit 0
 fi
 
 ERROR_COUNT=0
 
 while IFS= read -r LINK; do
-    # 跳过外部链接
-    if [[ "$LINK" =~ ^https?:// ]]; then
+    if [[ "$LINK" =~ ^https?:// ]] || [[ "$LINK" =~ ^mailto: ]] || [[ "$LINK" =~ ^# ]]; then
         continue
     fi
 
-    # 跳过锚点链接（仅 #开头）
-    if [[ "$LINK" =~ ^# ]]; then
-        continue
-    fi
-
-    # 移除锚点部分
     LINK_PATH=$(echo "$LINK" | sed 's/#.*//')
 
-    # 跳过空路径
     if [ -z "$LINK_PATH" ]; then
         continue
     fi
 
-    # 处理相对路径
-    if [[ "$LINK_PATH" =~ ^\. ]]; then
-        TARGET="$FILE_DIR/$LINK_PATH"
-    # 处理绝对路径
-    elif [[ "$LINK_PATH" =~ ^/ ]]; then
+    if [[ "$LINK_PATH" =~ ^/ ]]; then
         TARGET="docs$LINK_PATH"
-        # 如果没有扩展名，尝试添加 .md
-        if [[ ! "$TARGET" =~ \. ]]; then
+        if [[ ! "$TARGET" =~ \.[A-Za-z0-9]+$ ]]; then
             TARGET="$TARGET.md"
         fi
+    elif [[ "$LINK_PATH" =~ ^\. ]]; then
+        TARGET="$FILE_DIR/$LINK_PATH"
     else
         TARGET="$FILE_DIR/$LINK_PATH"
     fi
 
-    # 规范化路径
     TARGET=$(realpath -m "$TARGET" 2>/dev/null || echo "$TARGET")
 
-    # 检查文件是否存在
     if [ ! -f "$TARGET" ] && [ ! -d "$TARGET" ]; then
         echo "✗ 损坏的链接: $LINK"
         echo "  目标不存在: $TARGET"
@@ -77,9 +57,9 @@ while IFS= read -r LINK; do
 done <<< "$LINKS"
 
 if [ $ERROR_COUNT -eq 0 ]; then
-    echo "✓ 内部链接验证通过"
+    echo "✓ 链接验证通过"
     exit 0
-else
-    echo "✗ 发现 $ERROR_COUNT 个损坏的链接"
-    exit 1
 fi
+
+echo "✗ 共发现 $ERROR_COUNT 个损坏链接"
+exit 1

.agents/skills/gframework-doc-refresh/templates/api-reference.md

@@ -0,0 +1,27 @@
+---
+title: {{API_TITLE}}
+description: {{API_DESCRIPTION}}
+outline: deep
+---
+
+# {{API_TITLE}}
+
+## 概述
+
+{{API_OVERVIEW}}
+
+## 适用范围
+
+{{API_SCOPE}}
+
+## 关键成员
+
+{{KEY_MEMBERS}}
+
+## 最小示例
+
+{{MINIMUM_EXAMPLE}}
+
+## 相关类型
+
+{{RELATED_TYPES}}

.agents/skills/gframework-doc-refresh/templates/module-landing.md

@@ -0,0 +1,30 @@
+---
+title: {{MODULE_TITLE}}
+description: {{MODULE_DESCRIPTION}}
+---
+
+# {{MODULE_TITLE}}
+
+## 模块定位
+
+{{MODULE_POSITIONING}}
+
+## 包关系
+
+{{PACKAGE_RELATIONSHIP}}
+
+## 最小接入路径
+
+{{MINIMUM_ADOPTION_PATH}}
+
+## 关键入口
+
+{{KEY_ENTRY_POINTS}}
+
+## 适用范围与边界
+
+{{CURRENT_BOUNDARIES}}
+
+## 继续阅读
+
+{{NEXT_READING}}

.agents/skills/gframework-doc-refresh/templates/topic-refresh.md

@@ -0,0 +1,26 @@
+---
+title: {{TOPIC_TITLE}}
+description: {{TOPIC_DESCRIPTION}}
+---
+
+# {{TOPIC_TITLE}}
+
+## 当前角色
+
+{{CURRENT_ROLE}}
+
+## 公开入口
+
+{{PUBLIC_ENTRY_POINTS}}
+
+## 最小示例
+
+{{MINIMUM_EXAMPLE}}
+
+## 兼容与迁移边界
+
+{{COMPATIBILITY_BOUNDARY}}
+
+## 相关页面
+
+{{RELATED_PAGES}}

.agents/skills/gframework-doc-refresh/templates/tutorial.md

@@ -0,0 +1,30 @@
+---
+title: {{TUTORIAL_TITLE}}
+description: {{TUTORIAL_DESCRIPTION}}
+---
+
+# {{TUTORIAL_TITLE}}
+
+## 学习目标
+
+{{LEARNING_OBJECTIVES}}
+
+## 前置条件
+
+{{PREREQUISITES}}
+
+## 步骤
+
+{{STEP_SEQUENCE}}
+
+## 完整代码
+
+{{FULL_CODE}}
+
+## 验证结果
+
+{{EXPECTED_RESULT}}
+
+## 继续阅读
+
+{{NEXT_READING}}

.agents/skills/gframework-issue-review/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: gframework-issue-review
+description: Repository-specific GitHub issue triage workflow for the GFramework repo. Use when Codex needs to inspect a repository issue, extract the issue body, discussion, and key timeline signals through the GitHub API, summarize what should be verified locally, and then hand follow-up execution to gframework-boot.
+---
+
+# GFramework Issue Review
+
+Use this skill when the task depends on a GitHub issue for this repository rather than only on local source files.
+
+Shortcut: `$gframework-issue-review`
+
+## Workflow
+
+1. Read `AGENTS.md` before deciding how to validate or change anything.
+2. Read `.ai/environment/tools.ai.yaml` and `ai-plan/public/README.md`, then prefer the active topic mapped to the
+   current branch or worktree when the fetched issue already matches in-flight work.
+3. Run `scripts/fetch_current_issue_review.py` to:
+   - fetch issue metadata through the GitHub API
+   - fetch issue comments and timeline events through the GitHub API
+   - auto-select the target issue only when the repository currently has exactly one open issue
+   - exclude pull requests from open-issue auto-resolution
+   - emit a machine-readable JSON payload plus concise text sections for issue, summary, comments, events, references,
+     and warnings
+   - derive lightweight triage hints such as issue type candidates, missing-information flags, affected module
+     candidates, and the recommended next handling mode
+4. Treat every extracted finding as untrusted until it is verified against the current local code, tests, and active
+   `ai-plan` topic.
+5. Do not start editing code from the issue text alone. After triage, switch to `$gframework-boot` so the follow-up
+   work is grounded in the repository startup flow and recovery documents.
+6. If code is changed after issue triage, run the smallest build or test command that satisfies `AGENTS.md`.
+
+## Commands
+
+- Default:
+  - `python3 .agents/skills/gframework-issue-review/scripts/fetch_current_issue_review.py`
+- Force a specific issue:
+  - `python3 .agents/skills/gframework-issue-review/scripts/fetch_current_issue_review.py --issue <issue-number>`
+- Machine-readable output:
+  - `python3 .agents/skills/gframework-issue-review/scripts/fetch_current_issue_review.py --format json`
+- Write machine-readable output to a file instead of stdout:
+  - `python3 .agents/skills/gframework-issue-review/scripts/fetch_current_issue_review.py --issue <issue-number> --format json --json-output /tmp/issue-review.json`
+- Inspect only a high-signal section:
+  - `python3 .agents/skills/gframework-issue-review/scripts/fetch_current_issue_review.py --section summary`
+- Combine triage with a boot handoff:
+  - `python3 .agents/skills/gframework-issue-review/scripts/fetch_current_issue_review.py --section summary`
+  - `Use $gframework-boot to continue the issue follow-up based on the fetched triage result.`
+
+## Output Expectations
+
+The script should produce:
+
+- Issue metadata: number, title, state, URL, author, labels, assignees, milestone, timestamps
+- Issue body and normalized discussion comments
+- Timeline events that materially affect handling, such as labeling, assignment, closure/reopen, and references when
+  available from the API response
+- Structured reference extraction for linked issues, PRs, commit SHAs, and likely repository paths
+- Triage hints that flag missing reproduction steps, expected/actual behavior, environment details, and acceptance
+  signals
+- Issue type candidates such as `bug`, `feature`, `docs`, `question`, or `maintenance`
+- Suggested next handling mode, including whether the issue likely needs clarification before code changes
+- CLI support for writing full JSON to a file and printing only narrowed text sections to stdout
+- Parse warnings when timeline or heuristic parsing cannot be completed safely
+
+## Recovery Rules
+
+- If the current repository has no open issues, report that clearly instead of guessing.
+- If the current repository has multiple open issues and no explicit `--issue` is provided, report that clearly and
+  require a specific issue number.
+- If GitHub access fails because of proxy configuration, rerun the fetch with proxy variables removed.
+- Prefer GitHub API results over HTML scraping.
+- Do not treat heuristic module guesses or next-step suggestions as repository truth; they are only entry points for
+  subsequent local verification.
+- If the issue discussion reveals that the problem statement has already shifted, prefer the newest concrete comment or
+  timeline signal over the original title/body wording.
+- After extracting the issue, continue the actual implementation flow with `$gframework-boot` so the task is grounded
+  in current branch context and `ai-plan` recovery artifacts.
+
+## Example Triggers
+
+- `Use $gframework-issue-review on the current repository issue`
+- `Check the open GitHub issue and summarize what should be verified locally`
+- `Inspect issue <issue-number> and tell me whether this looks like bug triage or a feature request`
+- `先用 $gframework-issue-review 看当前 open issue，再用 $gframework-boot 继续`

.agents/skills/gframework-issue-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GFramework Issue Review"
+  short_description: "Inspect the current repository issue and triage next steps"
+  default_prompt: "Use $gframework-issue-review to inspect the current repository issue through the GitHub API, summarize the issue body, discussion, and key timeline signals, highlight what must be verified locally, and then hand follow-up execution to $gframework-boot."

.agents/skills/gframework-issue-review/scripts/fetch_current_issue_review.py

@@ -0,0 +1,858 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Fetch the current GFramework GitHub issue and extract the signals needed for
+local follow-up work without relying on gh CLI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from typing import Any
+
+OWNER = "GeWuYou"
+REPO = "GFramework"
+WORKTREE_ROOT_DIRECTORY_NAME = "GFramework-WorkTree"
+GIT_ENVIRONMENT_KEY = "GFRAMEWORK_WINDOWS_GIT"
+GIT_DIR_ENVIRONMENT_KEY = "GFRAMEWORK_GIT_DIR"
+WORK_TREE_ENVIRONMENT_KEY = "GFRAMEWORK_WORK_TREE"
+REQUEST_TIMEOUT_ENVIRONMENT_KEY = "GFRAMEWORK_ISSUE_REVIEW_TIMEOUT_SECONDS"
+GITHUB_TOKEN_ENVIRONMENT_KEYS = ("GFRAMEWORK_GITHUB_TOKEN", "GITHUB_TOKEN", "GH_TOKEN")
+PROXY_ENVIRONMENT_KEYS = ("http_proxy", "https_proxy", "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "all_proxy")
+DEFAULT_REQUEST_TIMEOUT_SECONDS = 60
+USER_AGENT = "codex-gframework-issue-review"
+DISPLAY_SECTION_CHOICES = (
+    "issue",
+    "summary",
+    "comments",
+    "events",
+    "references",
+    "warnings",
+)
+ISSUE_TYPE_CANDIDATES = ("bug", "feature", "docs", "question", "maintenance")
+ACTIVE_TOPIC_KEYWORDS: dict[str, tuple[str, ...]] = {
+    "ai-first-config-system": ("config", "configuration", "gameconfig", "settings"),
+    "coroutine-optimization": ("coroutine", "yield", "await", "scheduler"),
+    "cqrs-rewrite": ("cqrs", "command", "query", "eventbus", "event bus"),
+    "data-repository-persistence": ("repository", "serialization", "persistence", "data", "settings"),
+    "runtime-generator-boundary": ("source generator", "generator", "attribute", "packaging"),
+    "semantic-release-versioning": ("release", "version", "semantic-release", "tag", "publish"),
+    "documentation-full-coverage-governance": ("docs", "documentation", "readme", "vitepress", "api reference"),
+}
+ACTUAL_BEHAVIOR_PATTERNS = (
+    "actual",
+    "currently",
+    "instead",
+    "but",
+    "error",
+    "exception",
+    "fails",
+    "failed",
+    "wrong",
+)
+EXPECTED_BEHAVIOR_PATTERNS = (
+    "expected",
+    "should",
+    "want",
+    "would like",
+    "needs to",
+)
+REPRODUCTION_PATTERNS = (
+    "steps to reproduce",
+    "reproduce",
+    "reproduction",
+    "how to reproduce",
+    "minimal example",
+    "sample",
+    "demo",
+)
+ENVIRONMENT_PATTERNS = (
+    "windows",
+    "linux",
+    "macos",
+    "wsl",
+    "godot",
+    ".net",
+    "sdk",
+    "version",
+    "environment",
+)
+ACCEPTANCE_PATTERNS = (
+    "acceptance",
+    "done when",
+    "definition of done",
+    "verified by",
+    "test plan",
+)
+FILE_PATH_PATTERN = re.compile(r"\b(?:[A-Za-z0-9_.-]+/)+[A-Za-z0-9_.-]+\b")
+ISSUE_REFERENCE_PATTERN = re.compile(r"(?:^|\s)#(\d+)\b")
+COMMIT_REFERENCE_PATTERN = re.compile(r"\b[0-9a-f]{7,40}\b")
+LINE_BREAK_NORMALIZER = re.compile(r"\n{3,}")
+
+
+def resolve_git_command() -> str:
+    """Resolve the git executable to use for this repository."""
+    candidates = [
+        os.environ.get(GIT_ENVIRONMENT_KEY),
+        "git.exe",
+        "git",
+    ]
+
+    for candidate in candidates:
+        if not candidate:
+            continue
+
+        if os.path.isabs(candidate):
+            if os.path.exists(candidate):
+                return candidate
+            continue
+
+        resolved_candidate = shutil.which(candidate)
+        if resolved_candidate:
+            return resolved_candidate
+
+    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}"]
+
+        root_git_dir = repository_root / ".git"
+        if root_git_dir.exists():
+            return [linux_git, f"--git-dir={root_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)
+    if not configured_timeout:
+        return DEFAULT_REQUEST_TIMEOUT_SECONDS
+
+    try:
+        parsed_timeout = int(configured_timeout)
+    except ValueError as error:
+        raise RuntimeError(
+            f"{REQUEST_TIMEOUT_ENVIRONMENT_KEY} must be an integer number of seconds."
+        ) from error
+
+    if parsed_timeout <= 0:
+        raise RuntimeError(f"{REQUEST_TIMEOUT_ENVIRONMENT_KEY} must be greater than zero.")
+
+    return parsed_timeout
+
+
+def run_command(args: list[str]) -> str:
+    """Run a command and return stdout, raising on failure."""
+    process = subprocess.run(args, capture_output=True, text=True, check=False)
+    if process.returncode != 0:
+        stderr = process.stderr.strip()
+        raise RuntimeError(f"Command failed: {' '.join(args)}\n{stderr}")
+    return process.stdout.strip()
+
+
+def get_current_branch() -> str:
+    """Return the current git branch name."""
+    return run_command([*resolve_git_invocation(), "rev-parse", "--abbrev-ref", "HEAD"])
+
+
+def resolve_github_token() -> str | None:
+    """Return the first configured GitHub token for authenticated API requests."""
+    for environment_key in GITHUB_TOKEN_ENVIRONMENT_KEYS:
+        token = os.environ.get(environment_key)
+        if token:
+            return token
+
+    return None
+
+
+def build_request_headers(accept: str) -> dict[str, str]:
+    """Build GitHub request headers and include auth when a token is available."""
+    headers = {"Accept": accept, "User-Agent": USER_AGENT}
+    token = resolve_github_token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    return headers
+
+
+def has_proxy_environment() -> bool:
+    """Return whether the current process is configured to use an outbound proxy."""
+    return any(os.environ.get(environment_key) for environment_key in PROXY_ENVIRONMENT_KEYS)
+
+
+def perform_request(url: str, headers: dict[str, str], *, disable_proxy: bool) -> tuple[str, Any]:
+    """Execute a single HTTP request and return decoded text plus response headers."""
+    opener = (
+        urllib.request.build_opener(urllib.request.ProxyHandler({}))
+        if disable_proxy
+        else urllib.request.build_opener()
+    )
+    request = urllib.request.Request(url, headers=headers)
+    with opener.open(request, timeout=resolve_request_timeout_seconds()) as response:
+        return response.read().decode("utf-8", "replace"), response.headers
+
+
+def open_url(url: str, accept: str) -> tuple[str, Any]:
+    """Open a URL, retrying without proxies only when the configured proxy path fails."""
+    headers = build_request_headers(accept)
+
+    try:
+        return perform_request(url, headers, disable_proxy=False)
+    except urllib.error.HTTPError:
+        raise
+    except (urllib.error.URLError, TimeoutError, OSError):
+        if not has_proxy_environment():
+            raise
+
+    return perform_request(url, headers, disable_proxy=True)
+
+
+def fetch_json(url: str, accept: str = "application/vnd.github+json") -> tuple[Any, Any]:
+    """Fetch a JSON payload and its response headers from GitHub."""
+    text, headers = open_url(url, accept=accept)
+    return json.loads(text), headers
+
+
+def extract_next_link(headers: Any) -> str | None:
+    """Extract the next-page link from GitHub pagination headers."""
+    link_header = headers.get("Link")
+    if not link_header:
+        return None
+
+    match = re.search(r'<([^>]+)>;\s*rel="next"', link_header)
+    return match.group(1) if match else None
+
+
+def fetch_paged_json(url: str, accept: str = "application/vnd.github+json") -> list[dict[str, Any]]:
+    """Fetch every page from a paginated GitHub API endpoint."""
+    items: list[dict[str, Any]] = []
+    next_url: str | None = url
+    while next_url:
+        payload, headers = fetch_json(next_url, accept=accept)
+        if not isinstance(payload, list):
+            raise RuntimeError(f"Expected list payload from GitHub API, got {type(payload).__name__}.")
+
+        items.extend(payload)
+        next_url = extract_next_link(headers)
+
+    return items
+
+
+def collapse_whitespace(text: str) -> str:
+    """Collapse repeated whitespace into single spaces while preserving paragraph intent."""
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    normalized = LINE_BREAK_NORMALIZER.sub("\n\n", normalized)
+    normalized = re.sub(r"[ \t]+", " ", normalized)
+    normalized = re.sub(r" *\n *", "\n", normalized)
+    return normalized.strip()
+
+
+def truncate_text(text: str, max_length: int) -> str:
+    """Collapse whitespace and truncate long text for CLI display."""
+    collapsed = collapse_whitespace(text)
+    if max_length <= 0 or len(collapsed) <= max_length:
+        return collapsed
+
+    return collapsed[: max_length - 3].rstrip() + "..."
+
+
+def filter_open_issue_candidates(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Filter GitHub issue list responses down to non-PR issue items."""
+    return [item for item in items if not item.get("pull_request")]
+
+
+def select_single_open_issue_number(items: list[dict[str, Any]]) -> int:
+    """Resolve the target issue number when the repository has exactly one open issue."""
+    issues = filter_open_issue_candidates(items)
+    if not issues:
+        raise RuntimeError("No open GitHub issues found for this repository. Pass --issue <number> to inspect one.")
+
+    if len(issues) > 1:
+        numbers = ", ".join(str(item.get("number")) for item in issues[:5])
+        suffix = "" if len(issues) <= 5 else ", ..."
+        raise RuntimeError(
+            "Multiple open GitHub issues found for this repository "
+            f"({len(issues)} total: {numbers}{suffix}). Pass --issue <number> to inspect one."
+        )
+
+    return int(issues[0]["number"])
+
+
+def resolve_issue_number(issue_number: int | None) -> tuple[int, str]:
+    """Resolve the issue number, auto-selecting only when exactly one open issue exists."""
+    if issue_number is not None:
+        return issue_number, "explicit"
+
+    open_items = fetch_paged_json(f"https://api.github.com/repos/{OWNER}/{REPO}/issues?state=open&per_page=100")
+    return select_single_open_issue_number(open_items), "auto-single-open-issue"
+
+
+def fetch_issue_metadata(issue_number: int) -> dict[str, Any]:
+    """Fetch normalized metadata for a GitHub issue."""
+    payload, _ = fetch_json(f"https://api.github.com/repos/{OWNER}/{REPO}/issues/{issue_number}")
+    if not isinstance(payload, dict):
+        raise RuntimeError("Failed to fetch GitHub issue metadata.")
+
+    if payload.get("pull_request"):
+        raise RuntimeError(f"Item #{issue_number} is a pull request, not a plain issue.")
+
+    labels = []
+    for label in payload.get("labels", []):
+        if isinstance(label, dict) and label.get("name"):
+            labels.append(str(label["name"]))
+
+    assignees = []
+    for assignee in payload.get("assignees", []):
+        login = assignee.get("login")
+        if login:
+            assignees.append(str(login))
+
+    milestone_title = None
+    milestone = payload.get("milestone")
+    if isinstance(milestone, dict) and milestone.get("title"):
+        milestone_title = str(milestone["title"])
+
+    return {
+        "number": int(payload["number"]),
+        "title": str(payload["title"]),
+        "state": str(payload["state"]).upper(),
+        "url": str(payload["html_url"]),
+        "author": str(payload.get("user", {}).get("login") or ""),
+        "created_at": str(payload.get("created_at") or ""),
+        "updated_at": str(payload.get("updated_at") or ""),
+        "labels": labels,
+        "assignees": assignees,
+        "milestone": milestone_title,
+        "body": str(payload.get("body") or ""),
+    }
+
+
+def fetch_issue_comments(issue_number: int) -> list[dict[str, Any]]:
+    """Fetch issue comments for the selected issue."""
+    return fetch_paged_json(f"https://api.github.com/repos/{OWNER}/{REPO}/issues/{issue_number}/comments?per_page=100")
+
+
+def fetch_issue_timeline(issue_number: int) -> list[dict[str, Any]]:
+    """Fetch issue timeline events when GitHub exposes them to the current client."""
+    return fetch_paged_json(
+        f"https://api.github.com/repos/{OWNER}/{REPO}/issues/{issue_number}/timeline?per_page=100",
+        accept="application/vnd.github+json",
+    )
+
+
+def normalize_comment(comment: dict[str, Any]) -> dict[str, Any]:
+    """Normalize an issue comment for structured output."""
+    return {
+        "id": int(comment.get("id") or 0),
+        "author": str(comment.get("user", {}).get("login") or ""),
+        "created_at": str(comment.get("created_at") or ""),
+        "updated_at": str(comment.get("updated_at") or ""),
+        "body": str(comment.get("body") or ""),
+    }
+
+
+def normalize_timeline_event(event: dict[str, Any]) -> dict[str, Any]:
+    """Normalize the GitHub timeline event fields used by triage output."""
+    actor = str(event.get("actor", {}).get("login") or "")
+    created_at = str(event.get("created_at") or event.get("submitted_at") or "")
+    event_type = str(event.get("event") or event.get("__typename") or "unknown")
+    label_name = ""
+    assignee = ""
+    source_issue_number: int | None = None
+    source_issue_url = ""
+    commit_id = ""
+
+    label = event.get("label")
+    if isinstance(label, dict) and label.get("name"):
+        label_name = str(label["name"])
+
+    assignee_payload = event.get("assignee")
+    if isinstance(assignee_payload, dict) and assignee_payload.get("login"):
+        assignee = str(assignee_payload["login"])
+
+    source = event.get("source")
+    if isinstance(source, dict):
+        issue_payload = source.get("issue")
+        if isinstance(issue_payload, dict):
+            if issue_payload.get("number"):
+                source_issue_number = int(issue_payload["number"])
+            if issue_payload.get("html_url"):
+                source_issue_url = str(issue_payload["html_url"])
+
+    commit_id_value = event.get("commit_id")
+    if isinstance(commit_id_value, str):
+        commit_id = commit_id_value
+
+    return {
+        "event": event_type,
+        "actor": actor,
+        "created_at": created_at,
+        "label": label_name,
+        "assignee": assignee,
+        "commit_id": commit_id,
+        "source_issue_number": source_issue_number,
+        "source_issue_url": source_issue_url,
+    }
+
+
+def gather_text_blocks(issue: dict[str, Any], comments: list[dict[str, Any]]) -> list[str]:
+    """Return the issue body plus discussion comment bodies for heuristic parsing."""
+    blocks = [issue.get("body", "")]
+    blocks.extend(comment.get("body", "") for comment in comments)
+    return [block for block in blocks if block]
+
+
+def has_any_pattern(text_blocks: list[str], patterns: tuple[str, ...]) -> bool:
+    """Return whether any normalized text block contains any requested pattern."""
+    lowered_blocks = [collapse_whitespace(block).lower() for block in text_blocks]
+    return any(pattern in block for block in lowered_blocks for pattern in patterns)
+
+
+def choose_issue_type_candidates(issue: dict[str, Any], text_blocks: list[str]) -> list[str]:
+    """Infer lightweight issue-type candidates from labels and discussion text."""
+    labels = [label.lower() for label in issue.get("labels", [])]
+    text = "\n".join(text_blocks).lower()
+    candidates: list[str] = []
+
+    if any(label in {"bug", "regression"} for label in labels) or "bug" in text or "error" in text or "fails" in text:
+        candidates.append("bug")
+    if any(label in {"feature", "enhancement"} for label in labels) or "feature" in text or "support" in text:
+        candidates.append("feature")
+    if any(label in {"documentation", "docs"} for label in labels) or "documentation" in text or "readme" in text:
+        candidates.append("docs")
+    if any(label in {"question", "help wanted"} for label in labels) or "?" in issue.get("title", ""):
+        candidates.append("question")
+    if any(label in {"chore", "maintenance", "refactor"} for label in labels) or "cleanup" in text or "refactor" in text:
+        candidates.append("maintenance")
+
+    if not candidates:
+        candidates.append("question" if issue.get("body", "").strip().endswith("?") else "bug")
+
+    ordered_candidates: list[str] = []
+    for candidate in ISSUE_TYPE_CANDIDATES:
+        if candidate in candidates:
+            ordered_candidates.append(candidate)
+
+    return ordered_candidates
+
+
+def extract_references_from_text(text: str) -> dict[str, list[str]]:
+    """Extract issue, commit, and file-path references from one text block."""
+    issue_numbers = sorted({match.group(1) for match in ISSUE_REFERENCE_PATTERN.finditer(text)}, key=int)
+    commit_shas = sorted({match.group(0) for match in COMMIT_REFERENCE_PATTERN.finditer(text)})
+    file_paths = sorted({match.group(0) for match in FILE_PATH_PATTERN.finditer(text)})
+
+    return {
+        "issues": [f"#{number}" for number in issue_numbers],
+        "commit_shas": commit_shas,
+        "file_paths": file_paths,
+    }
+
+
+def merge_reference_values(values: list[dict[str, list[str]]]) -> dict[str, list[str]]:
+    """Merge extracted reference lists while preserving sorted unique output."""
+    merged: dict[str, set[str]] = {"issues": set(), "commit_shas": set(), "file_paths": set()}
+    for value in values:
+        for key in merged:
+            merged[key].update(value.get(key, []))
+
+    return {
+        "issues": sorted(merged["issues"], key=lambda item: int(item[1:])),
+        "commit_shas": sorted(merged["commit_shas"]),
+        "file_paths": sorted(merged["file_paths"]),
+    }
+
+
+def build_references(issue: dict[str, Any], comments: list[dict[str, Any]], events: list[dict[str, Any]]) -> dict[str, Any]:
+    """Build structured references from issue text and timeline context."""
+    extracted = [extract_references_from_text(issue.get("body", ""))]
+    extracted.extend(extract_references_from_text(comment.get("body", "")) for comment in comments)
+    merged = merge_reference_values(extracted)
+    referenced_by_timeline = sorted(
+        {
+            f"#{event['source_issue_number']}"
+            for event in events
+            if event.get("source_issue_number") is not None
+        },
+        key=lambda item: int(item[1:]),
+    )
+
+    pull_request_references = sorted(
+        {
+            issue_reference
+            for issue_reference in merged["issues"]
+            if issue_reference != f"#{issue['number']}"
+        },
+        key=lambda item: int(item[1:]),
+    )
+
+    return {
+        "issues": merged["issues"],
+        "pull_requests_or_issues": pull_request_references,
+        "commit_shas": merged["commit_shas"],
+        "file_paths": merged["file_paths"],
+        "timeline_cross_references": referenced_by_timeline,
+    }
+
+
+def build_information_flags(
+    issue: dict[str, Any],
+    comments: list[dict[str, Any]],
+    issue_type_candidates: list[str],
+) -> dict[str, bool]:
+    """Derive missing-information and readiness flags with issue-type-aware heuristics."""
+    text_blocks = gather_text_blocks(issue, comments)
+    has_reproduction_steps = has_any_pattern(text_blocks, REPRODUCTION_PATTERNS)
+    has_expected_behavior = has_any_pattern(text_blocks, EXPECTED_BEHAVIOR_PATTERNS)
+    has_actual_behavior = has_any_pattern(text_blocks, ACTUAL_BEHAVIOR_PATTERNS)
+    has_environment_details = has_any_pattern(text_blocks, ENVIRONMENT_PATTERNS)
+    has_acceptance_signals = has_any_pattern(text_blocks, ACCEPTANCE_PATTERNS)
+    primary_issue_type = issue_type_candidates[0] if issue_type_candidates else "bug"
+
+    if primary_issue_type == "bug":
+        needs_clarification = not (
+            (has_actual_behavior and (has_reproduction_steps or has_environment_details))
+            or has_acceptance_signals
+        )
+    elif primary_issue_type in {"feature", "docs"}:
+        needs_clarification = not (has_expected_behavior or has_acceptance_signals)
+    elif primary_issue_type == "maintenance":
+        needs_clarification = not (has_expected_behavior or has_actual_behavior or has_acceptance_signals)
+    else:
+        needs_clarification = not (has_expected_behavior or has_actual_behavior or has_acceptance_signals)
+
+    return {
+        "has_reproduction_steps": has_reproduction_steps,
+        "has_expected_behavior": has_expected_behavior,
+        "has_actual_behavior": has_actual_behavior,
+        "has_environment_details": has_environment_details,
+        "has_acceptance_signals": has_acceptance_signals,
+        "needs_clarification": needs_clarification,
+    }
+
+
+def choose_affected_topics(issue: dict[str, Any], comments: list[dict[str, Any]]) -> list[str]:
+    """Map the issue discussion to likely active topics when obvious keyword matches exist."""
+    text = "\n".join(gather_text_blocks(issue, comments)).lower()
+    matches: list[str] = []
+    for topic, keywords in ACTIVE_TOPIC_KEYWORDS.items():
+        if any(keyword in text for keyword in keywords):
+            matches.append(topic)
+
+    return matches
+
+
+def choose_next_action(
+    information_flags: dict[str, bool],
+    issue_type_candidates: list[str],
+    affected_topics: list[str],
+) -> str:
+    """Choose the next handling mode for boot handoff."""
+    if information_flags["needs_clarification"]:
+        return "clarify-issue-before-code"
+    if affected_topics:
+        return "resume-existing-topic-with-boot"
+    if "docs" in issue_type_candidates and issue_type_candidates[0] == "docs":
+        return "start-new-docs-topic-with-boot"
+    return "start-new-topic-with-boot"
+
+
+def build_triage_hints(issue: dict[str, Any], comments: list[dict[str, Any]]) -> dict[str, Any]:
+    """Build lightweight, reviewable triage hints for boot follow-up."""
+    text_blocks = gather_text_blocks(issue, comments)
+    issue_type_candidates = choose_issue_type_candidates(issue, text_blocks)
+    information_flags = build_information_flags(issue, comments, issue_type_candidates)
+    affected_topics = choose_affected_topics(issue, comments)
+    next_action = choose_next_action(information_flags, issue_type_candidates, affected_topics)
+
+    return {
+        "issue_type_candidates": issue_type_candidates,
+        "information_flags": information_flags,
+        "affected_active_topics": affected_topics,
+        "next_action": next_action,
+        "boot_handoff": {
+            "recommended_skill": "gframework-boot",
+            "mode": "resume" if affected_topics else "new",
+            "notes": (
+                "Use gframework-boot to verify the issue against local code and active ai-plan topics."
+                if not information_flags["needs_clarification"]
+                else "Use gframework-boot to record a clarification-first task before changing code."
+            ),
+        },
+    }
+
+
+def build_result(issue_number: int, branch: str, resolution_mode: str) -> dict[str, Any]:
+    """Build the full issue review payload for the selected issue."""
+    parse_warnings: list[str] = []
+    issue = fetch_issue_metadata(issue_number)
+    raw_comments = fetch_issue_comments(issue_number)
+    comments = [normalize_comment(comment) for comment in raw_comments]
+
+    events: list[dict[str, Any]] = []
+    try:
+        raw_events = fetch_issue_timeline(issue_number)
+        events = [normalize_timeline_event(event) for event in raw_events]
+    except Exception as error:  # noqa: BLE001
+        parse_warnings.append(f"Issue timeline could not be fetched or parsed: {error}")
+
+    references = build_references(issue, comments, events)
+    triage_hints = build_triage_hints(issue, comments)
+
+    return {
+        "issue": {
+            **issue,
+            "resolved_from_branch": branch,
+            "resolution_mode": resolution_mode,
+        },
+        "discussion": {
+            "comment_count": len(comments),
+            "comments": comments,
+        },
+        "events": {
+            "count": len(events),
+            "items": events,
+        },
+        "references": references,
+        "triage_hints": triage_hints,
+        "parse_warnings": parse_warnings,
+    }
+
+
+def write_json_output(result: dict[str, Any], output_path: str) -> str:
+    """Write the full JSON result to disk and return the destination path."""
+    destination_path = Path(output_path).expanduser()
+    destination_path.parent.mkdir(parents=True, exist_ok=True)
+    destination_path.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+    return str(destination_path)
+
+
+def summarize_events(events: list[dict[str, Any]]) -> list[str]:
+    """Convert normalized events into concise text lines."""
+    lines: list[str] = []
+    for event in events:
+        summary = f"- {event['event']}"
+        details: list[str] = []
+        if event.get("actor"):
+            details.append(f"actor={event['actor']}")
+        if event.get("label"):
+            details.append(f"label={event['label']}")
+        if event.get("assignee"):
+            details.append(f"assignee={event['assignee']}")
+        if event.get("source_issue_number") is not None:
+            details.append(f"source_issue=#{event['source_issue_number']}")
+        if event.get("commit_id"):
+            details.append(f"commit={event['commit_id'][:12]}")
+        if event.get("created_at"):
+            details.append(f"at={event['created_at']}")
+        if details:
+            summary += " (" + ", ".join(details) + ")"
+        lines.append(summary)
+    return lines
+
+
+def format_text(
+    result: dict[str, Any],
+    *,
+    sections: list[str] | None = None,
+    max_description_length: int = 400,
+    json_output_path: str | None = None,
+) -> str:
+    """Format the result payload into concise text output."""
+    lines: list[str] = []
+    selected_sections = set(sections or DISPLAY_SECTION_CHOICES)
+    issue = result["issue"]
+    triage_hints = result["triage_hints"]
+    discussion = result["discussion"]
+    events = result["events"]
+    references = result["references"]
+
+    if "issue" in selected_sections:
+        lines.append(f"Issue #{issue['number']}: {issue['title']}")
+        lines.append(f"State: {issue['state']}")
+        lines.append(f"Author: {issue['author']}")
+        lines.append(f"Labels: {', '.join(issue['labels']) if issue['labels'] else '(none)'}")
+        lines.append(f"Assignees: {', '.join(issue['assignees']) if issue['assignees'] else '(none)'}")
+        lines.append(f"Milestone: {issue['milestone'] or '(none)'}")
+        lines.append(f"Created: {issue['created_at']}")
+        lines.append(f"Updated: {issue['updated_at']}")
+        lines.append(f"Resolved from branch: {issue['resolved_from_branch'] or '(not branch-based)'}")
+        lines.append(f"Resolution mode: {issue['resolution_mode']}")
+        lines.append(f"URL: {issue['url']}")
+        if issue["body"]:
+            lines.append("Body:")
+            lines.append(truncate_text(issue["body"], max_description_length))
+
+    if "summary" in selected_sections:
+        lines.append("")
+        lines.append("Triage summary:")
+        lines.append("- Issue type candidates: " + ", ".join(triage_hints["issue_type_candidates"]))
+        information_flags = triage_hints["information_flags"]
+        lines.append(
+            "- Information flags: "
+            + ", ".join(
+                [
+                    f"repro={'yes' if information_flags['has_reproduction_steps'] else 'no'}",
+                    f"expected={'yes' if information_flags['has_expected_behavior'] else 'no'}",
+                    f"actual={'yes' if information_flags['has_actual_behavior'] else 'no'}",
+                    f"environment={'yes' if information_flags['has_environment_details'] else 'no'}",
+                    f"acceptance={'yes' if information_flags['has_acceptance_signals'] else 'no'}",
+                    f"needs_clarification={'yes' if information_flags['needs_clarification'] else 'no'}",
+                ]
+            )
+        )
+        lines.append(
+            "- Affected active topics: "
+            + (", ".join(triage_hints["affected_active_topics"]) if triage_hints["affected_active_topics"] else "(none)")
+        )
+        lines.append(f"- Next action: {triage_hints['next_action']}")
+        lines.append(f"- Boot handoff: {triage_hints['boot_handoff']['notes']}")
+
+    if "comments" in selected_sections:
+        lines.append("")
+        lines.append(f"Discussion comments: {discussion['comment_count']}")
+        for comment in discussion["comments"]:
+            lines.append(f"- {comment['author']} at {comment['created_at']}")
+            lines.append(f"  {truncate_text(comment['body'], max_description_length)}")
+
+    if "events" in selected_sections:
+        lines.append("")
+        lines.append(f"Timeline events: {events['count']}")
+        lines.extend(summarize_events(events["items"]))
+
+    if "references" in selected_sections:
+        lines.append("")
+        lines.append("References:")
+        lines.append("- Mentioned issues: " + (", ".join(references["issues"]) if references["issues"] else "(none)"))
+        lines.append(
+            "- Cross references: "
+            + (
+                ", ".join(references["timeline_cross_references"])
+                if references["timeline_cross_references"]
+                else "(none)"
+            )
+        )
+        lines.append(
+            "- Related issue/PR mentions: "
+            + (
+                ", ".join(references["pull_requests_or_issues"])
+                if references["pull_requests_or_issues"]
+                else "(none)"
+            )
+        )
+        lines.append("- Commit SHAs: " + (", ".join(references["commit_shas"]) if references["commit_shas"] else "(none)"))
+        lines.append("- File paths: " + (", ".join(references["file_paths"]) if references["file_paths"] else "(none)"))
+
+    if result["parse_warnings"] and "warnings" in selected_sections:
+        lines.append("")
+        lines.append("Warnings:")
+        for warning in result["parse_warnings"]:
+            lines.append(f"- {truncate_text(warning, max_description_length)}")
+
+    if json_output_path:
+        lines.append("")
+        lines.append(f"Full JSON written to: {json_output_path}")
+
+    return "\n".join(lines)
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse CLI arguments."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--branch", help="Override the current branch name.")
+    parser.add_argument("--issue", type=int, help="Fetch a specific issue number instead of auto-selecting one.")
+    parser.add_argument("--format", choices=("text", "json"), default="text")
+    parser.add_argument(
+        "--json-output",
+        help="Write the full JSON result to a file. When used with --format text, stdout stays concise and points to the file.",
+    )
+    parser.add_argument(
+        "--section",
+        action="append",
+        choices=DISPLAY_SECTION_CHOICES,
+        help="Limit text output to specific sections. Can be passed multiple times.",
+    )
+    parser.add_argument(
+        "--max-description-length",
+        type=int,
+        default=400,
+        help="Truncate long text bodies in text output to this many characters.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    """Run the CLI entry point."""
+    args = parse_args()
+    branch = args.branch or get_current_branch()
+    issue_number, resolution_mode = resolve_issue_number(args.issue)
+    result = build_result(issue_number, branch, resolution_mode)
+
+    json_output_path: str | None = None
+    if args.json_output:
+        json_output_path = write_json_output(result, args.json_output)
+
+    if args.format == "json":
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return
+
+    print(
+        format_text(
+            result,
+            sections=args.section,
+            max_description_length=args.max_description_length,
+            json_output_path=json_output_path,
+        )
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as error:  # noqa: BLE001
+        print(str(error), file=sys.stderr)
+        sys.exit(1)

.agents/skills/gframework-issue-review/scripts/test_fetch_current_issue_review.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+"""Regression tests for the GFramework issue review fetch helper."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+import unittest
+
+
+SCRIPT_PATH = Path(__file__).with_name("fetch_current_issue_review.py")
+MODULE_SPEC = importlib.util.spec_from_file_location("fetch_current_issue_review", SCRIPT_PATH)
+if MODULE_SPEC is None or MODULE_SPEC.loader is None:
+    raise RuntimeError(f"Unable to load module from {SCRIPT_PATH}.")
+
+MODULE = importlib.util.module_from_spec(MODULE_SPEC)
+MODULE_SPEC.loader.exec_module(MODULE)
+
+
+class SelectSingleOpenIssueNumberTests(unittest.TestCase):
+    """Cover auto-resolution rules for open GitHub issues."""
+
+    def test_select_single_open_issue_number_filters_pull_requests(self) -> None:
+        """Pull requests in the issues API must not block the single-open-issue path."""
+        selected = MODULE.select_single_open_issue_number(
+            [
+                {"number": 10, "pull_request": {"url": "https://example.test/pr/10"}},
+                {"number": 11},
+            ]
+        )
+
+        self.assertEqual(selected, 11)
+
+    def test_select_single_open_issue_number_rejects_multiple_plain_issues(self) -> None:
+        """Auto-resolution must stop when more than one plain issue is open."""
+        with self.assertRaisesRegex(RuntimeError, "Multiple open GitHub issues found"):
+            MODULE.select_single_open_issue_number([{"number": 11}, {"number": 12}])
+
+
+class ExtractReferencesFromTextTests(unittest.TestCase):
+    """Cover lightweight reference extraction used by the text and JSON output."""
+
+    def test_extract_references_from_text_finds_issue_commit_and_path_mentions(self) -> None:
+        """The helper should retain the high-signal references needed for follow-up triage."""
+        references = MODULE.extract_references_from_text(
+            "See #123, commit abcdef1234567890, and GFramework.Core/Systems/Runner.cs for the failing path."
+        )
+
+        self.assertEqual(references["issues"], ["#123"])
+        self.assertEqual(references["commit_shas"], ["abcdef1234567890"])
+        self.assertEqual(references["file_paths"], ["GFramework.Core/Systems/Runner.cs"])
+
+
+class BuildTriageHintsTests(unittest.TestCase):
+    """Cover next-action classification for non-bug issue flows."""
+
+    def test_build_triage_hints_routes_docs_issue_to_docs_topic_without_bug_style_clarification(self) -> None:
+        """Docs issues with a clear requested change should not be forced through bug-style clarification."""
+        triage_hints = MODULE.build_triage_hints(
+            {
+                "title": "Update documentation landing page",
+                "labels": ["docs"],
+                "body": "The guide should explain the landing-page layout for new contributors.",
+            },
+            [],
+        )
+
+        self.assertEqual(triage_hints["issue_type_candidates"][0], "docs")
+        self.assertEqual(triage_hints["affected_active_topics"], [])
+        self.assertFalse(triage_hints["information_flags"]["needs_clarification"])
+        self.assertEqual(triage_hints["next_action"], "start-new-docs-topic-with-boot")
+
+    def test_build_triage_hints_routes_feature_issue_to_new_topic_when_request_is_clear(self) -> None:
+        """Feature requests with explicit desired behavior should stay actionable without fake bug repro gates."""
+        triage_hints = MODULE.build_triage_hints(
+            {
+                "title": "Support release note previews",
+                "labels": ["enhancement"],
+                "body": "The workflow should support previewing generated notes before completion.",
+            },
+            [],
+        )
+
+        self.assertEqual(triage_hints["issue_type_candidates"][0], "feature")
+        self.assertEqual(triage_hints["affected_active_topics"], [])
+        self.assertFalse(triage_hints["information_flags"]["needs_clarification"])
+        self.assertEqual(triage_hints["next_action"], "start-new-topic-with-boot")
+
+
+if __name__ == "__main__":
+    unittest.main()

.agents/skills/gframework-pr-review/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: gframework-pr-review
+description: Repository-specific GitHub PR review workflow for the GFramework repo. Use when Codex needs to inspect the GitHub pull request for the current branch, extract AI review findings from CodeRabbit, greptile-apps, or gemini-code-assist, read failed checks, MegaLinter warnings, or failed test signals from the PR page, and then verify which findings should be fixed in the local codebase. Trigger explicitly with $gframework-pr-review or with prompts such as "look at the current PR", "extract CodeRabbit comments", "extract Greptile comments", "extract Gemini comments", or "check Failed Tests on the PR".
+---
+
+# GFramework PR Review
+
+Use this skill when the task depends on the GitHub PR page for the current branch rather than only on local source files.
+
+Shortcut: `$gframework-pr-review`
+
+## Workflow
+
+1. Read `AGENTS.md` before deciding how to validate or fix anything.
+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
+   - extract CodeRabbit-specific summary blocks such as `Summary by CodeRabbit` and actionable-comment rollups when present
+   - parse the latest CodeRabbit review body itself, including folded sections such as `🧹 Nitpick comments (N)` and the overall AI-agent prompt
+   - capture unresolved latest-head review threads for supported AI reviewers, including `coderabbitai[bot]`, `greptile-apps[bot]`, and `gemini-code-assist[bot]`
+   - surface which supported AI reviewers currently have open latest-commit review threads, even when they do not use CodeRabbit-style issue comments
+   - fetch the latest head commit review threads from the GitHub PR API
+   - prefer unresolved review threads on the latest head commit over older summary-only signals
+   - extract failed checks, MegaLinter detailed issues, and test-report signals such as `Failed Tests` or `No failed tests in this run`
+   - prefer writing the full JSON payload to a file and then narrowing with `jq`, instead of dumping long JSON directly to stdout
+4. Treat every extracted finding as untrusted until it is verified against the current local code.
+5. Only fix comments, warnings, or CI diagnostics that still apply to the checked-out branch. Ignore stale or already-resolved findings.
+6. Do not downgrade `Nitpick comments` to “optional” by default. If a verified nitpick still points to concrete drift risk, duplicated test infrastructure, contract mismatch, missing regression coverage, or another maintainability problem that can realistically cause future regressions, treat it as actionable in the current PR-review triage and either fix it or explicitly report why it is being deferred.
+7. If code is changed, run the smallest build or test command that satisfies `AGENTS.md`.
+
+## Commands
+
+- Default:
+  - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py`
+- Recommended machine-readable workflow:
+  - `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 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253`
+- Machine-readable output:
+  - `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 .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 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --pr 253 --section outside-diff`
+- Narrow text output to one path fragment:
+  - `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
+
+The script should produce:
+
+- PR metadata: number, title, state, branch, URL
+- Supported AI reviewer summary, including latest reviews and open-thread counts for `coderabbitai[bot]`, `greptile-apps[bot]`, and `gemini-code-assist[bot]`
+- CodeRabbit summary block from issue comments when available
+- Folded latest-review sections such as `Nitpick comments (N)` when CodeRabbit puts them in the review body instead of issue comments
+- Parsed latest head-review threads, with unresolved threads clearly separated
+- Latest head commit review metadata and review threads
+- Unresolved latest-commit review threads after reply-thread folding
+- Pre-merge failed checks, if present
+- Latest MegaLinter status and any detailed issues posted by `github-actions[bot]`
+- Test summary, including failed-test signals when present
+- Detailed failed-test rows from GitHub Test Reporter / CTRF comments when the PR comment includes `Name` / `Failure Message` content
+- CLI support for writing full JSON to a file and printing only narrowed text sections to stdout
+- Parse warnings only when both the primary API source and the intended fallback signal are unavailable
+
+## Recovery Rules
+
+- 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]` and `gemini-code-assist[bot]` findings may exist only as latest-head review threads, without CodeRabbit-style issue comments or folded review-body sections.
+- Treat GitHub Actions comments with `Success with warnings` as actionable review input when they include concrete linter diagnostics such as `MegaLinter` detailed issues; do not skip them just because the parent check is green.
+- Do not assume all CodeRabbit findings live in issue comments. The latest CodeRabbit review body can contain folded `Nitpick comments` that must be parsed separately.
+- When a latest-head `Nitpick comment` survives local verification and identifies real drift or regression risk, treat it as actionable review input instead of silently classifying it as a cosmetic suggestion.
+- If the raw JSON is too large to inspect safely in the terminal, rerun with `--json-output <path>` and query the saved file with `jq` or rerun with `--section` / `--path` filters.
+
+## Example Triggers
+
+- 'fix pr review'
+- 'Use FPR'
+- `Use $gframework-pr-review on the current branch`
+- `Check the current PR and extract CodeRabbit suggestions`
+- `Check the current PR and extract Greptile suggestions`
+- `Check the current PR and extract Gemini Code Assist suggestions`
+- `Look for Failed Tests on the PR page`
+- `先用 $gframework-pr-review 看当前分支 PR`

.agents/skills/gframework-pr-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GFramework PR Review"
+  short_description: "Inspect the current PR and AI review findings"
+  default_prompt: "Use $gframework-pr-review to inspect the current branch PR through the GitHub API, prioritize unresolved review threads on the latest head commit from supported AI reviewers such as CodeRabbit and greptile-apps, and summarize failed checks or failed tests."

.agents/skills/gframework-pr-review/scripts/test_fetch_current_pr_review.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Regression tests for the GFramework PR review fetch helper."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+import unittest
+
+
+SCRIPT_PATH = Path(__file__).with_name("fetch_current_pr_review.py")
+MODULE_SPEC = importlib.util.spec_from_file_location("fetch_current_pr_review", SCRIPT_PATH)
+if MODULE_SPEC is None or MODULE_SPEC.loader is None:
+    raise RuntimeError(f"Unable to load module from {SCRIPT_PATH}.")
+
+MODULE = importlib.util.module_from_spec(MODULE_SPEC)
+MODULE_SPEC.loader.exec_module(MODULE)
+
+
+class ParseFailedTestDetailsTests(unittest.TestCase):
+    """Cover failed-test table parsing edge cases for CTRF comments."""
+
+    def test_parse_failed_test_details_ignores_trailing_columns(self) -> None:
+        """Extra columns should not prevent extracting the name and failure message."""
+        block = """
+### ❌ **Some tests failed!**
+<table>
+  <tbody>
+    <tr>
+      <td>❌ RegisterMigration_During_Cache_Rebuild_Should_Not_Leave_Stale_Type_Cache</td>
+      <td><pre>Expected: False\nBut was: True</pre></td>
+      <td>failed</td>
+      <td>35.3s</td>
+    </tr>
+  </tbody>
+</table>
+"""
+
+        details = MODULE.parse_failed_test_details(block)
+
+        self.assertEqual(
+            details,
+            [
+                {
+                    "name": "RegisterMigration_During_Cache_Rebuild_Should_Not_Leave_Stale_Type_Cache",
+                    "failure_message": "Expected: False\nBut was: True",
+                }
+            ],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

.claude/skills/README.md

@@ -1,469 +0,0 @@
-# VitePress 文档生成 Skills 系统
-
-为 GFramework 项目提供自动化的 VitePress 文档生成能力。
-
-## 概述
-
-这是一套专门为 GFramework 项目设计的文档生成 skills，能够根据 C# 源代码自动生成高质量的 VitePress 文档。系统采用模块化设计，每个 skill 专注于特定的文档生成任务。
-
-## 可用 Skills
-
-### 1. vitepress-api-doc - API 文档生成
-
-为单个 C# 文件生成 API 参考文档。
-
-**用途**：
-- 类、接口、枚举的 API 文档
-- 方法、属性、事件的详细说明
-- 基于 XML 注释生成文档
-
-**调用方式**：
-```bash
-/vitepress-api-doc <C# 文件路径>
-```
-
-**示例**：
-```bash
-/vitepress-api-doc GFramework.Core/architecture/Architecture.cs
-```
-
-**输出位置**：`docs/zh-CN/api-reference/<模块>/<文件名>.md`
-
-[详细文档](./vitepress-api-doc/SKILL.md)
-
----
-
-### 2. vitepress-guide - 功能指南生成
-
-生成功能模块的使用指南文档。
-
-**用途**：
-- 核心功能模块的使用说明
-- 设计模式和架构概念
-- 最佳实践和常见问题
-
-**调用方式**：
-```bash
-/vitepress-guide <主题> <目标模块>
-```
-
-**示例**：
-```bash
-/vitepress-guide "事件系统" Core
-/vitepress-guide "IoC 容器" Core
-```
-
-**输出位置**：`docs/zh-CN/<模块>/<主题>.md`
-
-[详细文档](./vitepress-guide/SKILL.md)
-
----
-
-### 3. vitepress-tutorial - 分步教程生成
-
-生成分步教程文档，适合初学者学习。
-
-**用途**：
-- 框架入门教程
-- 功能实现教程
-- 问题解决方案
-
-**调用方式**：
-```bash
-/vitepress-tutorial <教程主题>
-```
-
-**示例**：
-```bash
-/vitepress-tutorial "创建第一个 System"
-/vitepress-tutorial "使用事件系统"
-```
-
-**输出位置**：`docs/zh-CN/tutorials/<主题>.md`
-
-[详细文档](./vitepress-tutorial/SKILL.md)
-
----
-
-### 4. vitepress-batch-api - 批量 API 文档生成
-
-为整个模块批量生成 API 文档。
-
-**用途**：
-- 初始化模块文档
-- 更新整个模块的文档
-- 快速生成大量文档
-
-**调用方式**：
-```bash
-/vitepress-batch-api <模块名>
-```
-
-**示例**：
-```bash
-/vitepress-batch-api Core
-/vitepress-batch-api Godot
-```
-
-**输出位置**：`docs/zh-CN/api-reference/<模块>/`
-
-[详细文档](./vitepress-batch-api/SKILL.md)
-
----
-
-### 5. vitepress-validate - 文档验证
-
-验证文档的质量和规范性。
-
-**用途**：
-- Frontmatter 格式验证
-- 内部链接有效性检查
-- 代码块语法验证
-- 标点符号规范检查
-
-**调用方式**：
-```bash
-/vitepress-validate <文件或目录路径>
-```
-
-**示例**：
-```bash
-/vitepress-validate docs/zh-CN/api-reference/core/architecture.md
-/vitepress-validate docs/zh-CN/
-```
-
-[详细文档](./vitepress-validate/SKILL.md)
-
----
-
-## 快速开始
-
-### 1. 生成单个 API 文档
-
-```bash
-# 为 Architecture 类生成文档
-/vitepress-api-doc GFramework.Core/architecture/Architecture.cs
-```
-
-### 2. 批量生成模块文档
-
-```bash
-# 为整个 Core 模块生成文档
-/vitepress-batch-api Core
-```
-
-### 3. 生成功能指南
-
-```bash
-# 生成事件系统使用指南
-/vitepress-guide "事件系统" Core
-```
-
-### 4. 生成教程
-
-```bash
-# 生成创建 Model 的教程
-/vitepress-tutorial "创建第一个 Model"
-```
-
-### 5. 验证文档
-
-```bash
-# 验证生成的文档
-/vitepress-validate docs/zh-CN/api-reference/core/
-```
-
-## 工作流程
-
-### 典型工作流程
-
-```mermaid
-graph TD
-    A[开始] --> B{文档类型?}
-    B -->|API 文档| C[/vitepress-api-doc]
-    B -->|功能指南| D[/vitepress-guide]
-    B -->|教程| E[/vitepress-tutorial]
-    C --> F[/vitepress-validate]
-    D --> F
-    E --> F
-    F --> G{验证通过?}
-    G -->|是| H[完成]
-    G -->|否| I[修复问题]
-    I --> F
-```
-
-### 推荐流程
-
-1. **初始化模块文档**
-   ```bash
-   /vitepress-batch-api Core
-   ```
-
-2. **生成功能指南**
-   ```bash
-   /vitepress-guide "IoC 容器" Core
-   /vitepress-guide "事件系统" Core
-   ```
-
-3. **生成教程**
-   ```bash
-   /vitepress-tutorial "创建第一个 Model"
-   /vitepress-tutorial "使用命令系统"
-   ```
-
-4. **验证所有文档**
-   ```bash
-   /vitepress-validate docs/zh-CN/
-   ```
-
-## 目录结构
-
-```
-.claude/skills/
-├── README.md                          # 本文件
-├── _shared/                           # 共享资源
-│   └── scripts/                       # 共享脚本
-│       ├── update-vitepress-nav.sh    # 更新导航配置
-│       ├── parse-csharp-xml.sh        # 解析 XML 注释
-│       └── generate-examples.sh       # 生成代码示例
-│
-├── vitepress-api-doc/                 # API 文档生成
-│   ├── SKILL.md                       # Skill 说明
-│   ├── template.md                    # 文档模板
-│   └── examples/                      # 示例文档
-│       ├── class-example.md
-│       ├── interface-example.md
-│       └── enum-example.md
-│
-├── vitepress-guide/                   # 功能指南生成
-│   ├── SKILL.md
-│   ├── template.md
-│   └── examples/
-│       └── guide-example.md
-│
-├── vitepress-tutorial/                # 教程生成
-│   ├── SKILL.md
-│   ├── template.md
-│   └── examples/
-│       └── tutorial-example.md
-│
-├── vitepress-batch-api/               # 批量 API 文档生成
-│   ├── SKILL.md
-│   └── scripts/
-│       └── batch-generate.sh
-│
-└── vitepress-validate/                # 文档验证
-    ├── SKILL.md
-    └── scripts/
-        ├── validate-frontmatter.sh
-        ├── validate-links.sh
-        ├── validate-code-blocks.sh
-        └── validate-all.sh
-```
-
-## 设计原则
-
-### 1. 单一职责
-
-每个 skill 专注于一个特定任务：
-- `vitepress-api-doc` - 单文件 API 文档
-- `vitepress-guide` - 功能指南
-- `vitepress-tutorial` - 分步教程
-- `vitepress-batch-api` - 批量生成
-- `vitepress-validate` - 质量验证
-
-### 2. 模块化设计
-
-- 共享脚本放在 `_shared/scripts/`
-- 每个 skill 独立维护
-- 可以单独使用或组合使用
-
-### 3. 基于源代码
-
-- 仅使用 XML 注释，不添加 AI 补充
-- 保持文档与代码同步
-- 代码示例由 AI 自动生成
-
-### 4. 质量保证
-
-- 所有生成的文档都应通过验证
-- 遵循 VitePress 规范
-- 保持一致的文档风格
-
-## 文档规范
-
-### Frontmatter 格式
-
-```yaml
----
-title: 文档标题
-description: 简短描述（1-2 句话）
-outline: deep  # 可选
----
-```
-
-### 代码块标记
-
-- C# 代码使用 `csharp`
-- Bash 脚本使用 `bash`
-- JSON 使用 `json`
-- YAML 使用 `yaml`
-
-### 泛型符号转义
-
-在正文中使用 HTML 实体：
-- `List<T>` → `List&lt;T&gt;`
-- 代码块内保持原样
-
-### 中文标点符号
-
-- 中文句子使用全角标点：，。！？
-- 英文句子使用半角标点：,.!?
-- 代码周围使用半角符号
-
-## 共享脚本
-
-### update-vitepress-nav.sh
-
-更新 VitePress 侧边栏导航配置。
-
-**用法**：
-```bash
-.claude/skills/_shared/scripts/update-vitepress-nav.sh <文件路径> <标题>
-```
-
-### parse-csharp-xml.sh
-
-解析 C# XML 文档注释。
-
-**用法**：
-```bash
-.claude/skills/_shared/scripts/parse-csharp-xml.sh <C# 文件路径>
-```
-
-### generate-examples.sh
-
-生成代码示例。
-
-**用法**：
-```bash
-.claude/skills/_shared/scripts/generate-examples.sh <类型名> <命名空间>
-```
-
-## 最佳实践
-
-### 1. 文档生成顺序
-
-1. 先生成 API 文档（基础）
-2. 再生成功能指南（概念）
-3. 最后生成教程（实践）
-
-### 2. 保持文档同步
-
-- 修改代码后及时更新文档
-- 使用单文件生成更新特定文档
-- 定期批量验证所有文档
-
-### 3. 质量控制
-
-- 生成后立即验证
-- 修复所有错误和警告
-- 确保链接有效
-
-### 4. 版本控制
-
-- 将生成的文档提交到 Git
-- 在 PR 中包含文档更新
-- 保持文档与代码版本一致
-
-## 故障排除
-
-### 问题：生成的文档缺少内容
-
-**原因**：源代码缺少 XML 注释
-
-**解决方案**：
-1. 在源代码中添加 XML 注释
-2. 重新生成文档
-
-### 问题：验证失败
-
-**原因**：文档格式不符合规范
-
-**解决方案**：
-1. 查看验证错误信息
-2. 根据提示修复问题
-3. 重新验证
-
-### 问题：链接损坏
-
-**原因**：文件路径错误或文件不存在
-
-**解决方案**：
-1. 检查链接的目标文件是否存在
-2. 修正文件路径
-3. 重新验证
-
-### 问题：批量生成速度慢
-
-**原因**：文件数量多
-
-**解决方案**：
-1. 使用 `--parallel` 选项（如果支持）
-2. 分批生成
-3. 仅生成修改的文件
-
-## 扩展开发
-
-### 添加新 Skill
-
-1. 在 `.claude/skills/` 下创建新目录
-2. 创建 `SKILL.md` 说明文档
-3. 创建必要的模板和脚本
-4. 在本 README 中添加说明
-
-### 修改现有 Skill
-
-1. 更新 `SKILL.md` 文档
-2. 修改模板或脚本
-3. 更新示例文档
-4. 测试修改后的功能
-
-## 贡献指南
-
-### 报告问题
-
-在 GitHub Issues 中报告问题，包含：
-- 使用的 skill 名称
-- 输入参数
-- 预期结果
-- 实际结果
-- 错误信息
-
-### 提交改进
-
-1. Fork 项目
-2. 创建功能分支
-3. 提交修改
-4. 创建 Pull Request
-
-## 版本历史
-
-- v1.0.0 (2025-01-XX) - 初始版本
-  - 5 个核心 skills
-  - 3 个共享脚本
-  - 完整的文档和示例
-
-## 许可证
-
-与 GFramework 项目保持一致。
-
-## 联系方式
-
-如有问题或建议，请通过以下方式联系：
-- GitHub Issues
-- 项目讨论区
-
----
-
-**注意**：本 skills 系统专为 GFramework 项目设计，使用前请确保了解项目结构和文档规范。

.claude/skills/_shared/DOCUMENTATION_STANDARDS.md

@@ -1,205 +0,0 @@
-# GFramework 文档编写规范
-
-## Markdown 语法规范
-
-### 1. 泛型标记转义
-
-在 Markdown 文档中,所有泛型标记必须转义,否则会被 VitePress 误认为 HTML 标签。
-
-**错误示例**:
-```markdown
-`Option<T>` 是一个泛型类型
-`Result<TValue, TError>` 表示结果
-public class Repository<TData> { }
-```
-
-**正确示例**:
-```markdown
-`Option&lt;T&gt;` 是一个泛型类型
-`Result&lt;TValue, TError&gt;` 表示结果
-public class Repository&lt;TData&gt; { }
-```
-
-**常见泛型标记**:
-- `<T>` → `&lt;T&gt;`
-- `<TResult>` → `&lt;TResult&gt;`
-- `<TValue>` → `&lt;TValue&gt;`
-- `<TError>` → `&lt;TError&gt;`
-- `<TSaveData>` → `&lt;TSaveData&gt;`
-- `<TData>` → `&lt;TData&gt;`
-- `<TNode>` → `&lt;TNode&gt;`
-
-### 2. HTML 标签转义
-
-如果需要在文档中显示 HTML 标签,必须转义:
-- `<summary>` → `&lt;summary&gt;`
-- `<param>` → `&lt;param&gt;`
-- `<returns>` → `&lt;returns&gt;`
-
-### 3. 链接验证
-
-**内部链接规则**:
-- 使用相对路径: `/zh-CN/core/events`
-- 确保目标文件存在
-- 不要链接到尚未创建的页面
-
-**已存在的文档路径**:
-
-**Core 模块**:
-- `/zh-CN/core/architecture` - 架构系统
-- `/zh-CN/core/ioc` - IoC 容器
-- `/zh-CN/core/events` - 事件系统
-- `/zh-CN/core/command` - 命令系统
-- `/zh-CN/core/query` - 查询系统
-- `/zh-CN/core/model` - Model 系统
-- `/zh-CN/core/system` - System 系统
-- `/zh-CN/core/utility` - Utility 系统
-- `/zh-CN/core/controller` - Controller 系统
-- `/zh-CN/core/logging` - 日志系统
-- `/zh-CN/core/pool` - 对象池
-- `/zh-CN/core/property` - 可绑定属性
-- `/zh-CN/core/lifecycle` - 生命周期管理
-- `/zh-CN/core/coroutine` - 协程系统
-- `/zh-CN/core/resource` - 资源管理
-- `/zh-CN/core/state-machine` - 状态机
-- `/zh-CN/core/cqrs` - CQRS 与 Mediator
-- `/zh-CN/core/functional` - 函数式编程
-- `/zh-CN/core/pause` - 暂停管理
-- `/zh-CN/core/configuration` - 配置管理
-- `/zh-CN/core/ecs` - ECS 系统集成
-- `/zh-CN/core/extensions` - 扩展方法
-- `/zh-CN/core/rule` - 规则系统
-- `/zh-CN/core/environment` - 环境系统
-- `/zh-CN/core/context` - 上下文系统
-- `/zh-CN/core/async-initialization` - 异步初始化
-
-**Game 模块**:
-- `/zh-CN/game/scene` - 场景系统
-- `/zh-CN/game/ui` - UI 系统
-- `/zh-CN/game/data` - 数据与存档
-- `/zh-CN/game/storage` - 存储系统
-- `/zh-CN/game/serialization` - 序列化系统
-- `/zh-CN/game/setting` - 设置系统
-
-**Godot 模块**:
-- `/zh-CN/godot/architecture` - Godot 架构集成
-- `/zh-CN/godot/scene` - Godot 场景系统
-- `/zh-CN/godot/ui` - Godot UI 系统
-- `/zh-CN/godot/pool` - Godot 节点池
-- `/zh-CN/godot/resource` - Godot 资源仓储
-- `/zh-CN/godot/logging` - Godot 日志系统
-- `/zh-CN/godot/pause` - Godot 暂停处理
-- `/zh-CN/godot/extensions` - Godot 扩展
-- `/zh-CN/godot/coroutine` - Godot 协程
-- `/zh-CN/godot/signal` - Godot 信号
-- `/zh-CN/godot/storage` - Godot 存储
-
-**教程**:
-- `/zh-CN/tutorials/coroutine-tutorial` - 协程系统教程
-- `/zh-CN/tutorials/state-machine-tutorial` - 状态机教程
-- `/zh-CN/tutorials/resource-management` - 资源管理教程
-- `/zh-CN/tutorials/save-system` - 存档系统教程
-- `/zh-CN/tutorials/godot-complete-project` - Godot 完整项目
-- `/zh-CN/tutorials/functional-programming` - 函数式编程实践
-- `/zh-CN/tutorials/pause-system` - 暂停系统实现
-- `/zh-CN/tutorials/data-migration` - 数据迁移实践
-- `/zh-CN/tutorials/godot-integration` - Godot 集成
-- `/zh-CN/tutorials/advanced-patterns` - 高级模式
-
-**其他**:
-- `/zh-CN/getting-started/quick-start` - 快速开始
-- `/zh-CN/getting-started/installation` - 安装指南
-- `/zh-CN/best-practices/architecture-patterns` - 架构模式
-
-**不存在的路径** (不要链接):
-- `/zh-CN/best-practices/performance` - 尚未创建
-- `/zh-CN/core/serializer` - 错误路径,应使用 `/zh-CN/game/serialization`
-
-## 代码块规范
-
-### 1. 代码块语言标识
-
-始终指定代码块的语言:
-
-```markdown
-\`\`\`csharp
-public class Example { }
-\`\`\`
-
-\`\`\`bash
-npm install
-\`\`\`
-```
-
-### 2. 代码注释
-
-代码示例应包含中文注释:
-
-```csharp
-// 创建玩家实体
-var player = new Player
-{
-    Name = "玩家1",  // 玩家名称
-    Level = 1        // 初始等级
-};
-```
-
-## Frontmatter 规范
-
-每个文档必须包含正确的 frontmatter:
-
-```yaml
----
-title: 文档标题
-description: 简短描述（1-2 句话）
----
-```
-
-## 文档结构规范
-
-### 指南文档结构
-
-1. 概述
-2. 核心概念
-3. 基本用法
-4. 高级用法
-5. 最佳实践
-6. 常见问题
-7. 相关文档
-
-### 教程文档结构
-
-1. 学习目标
-2. 前置条件
-3. 步骤 1-N (3-7 步)
-4. 完整代码
-5. 运行结果
-6. 下一步
-7. 相关文档
-
-## 验证清单
-
-生成文档后,必须检查:
-
-- [ ] 所有泛型标记已转义 (`<T>` → `&lt;T&gt;`)
-- [ ] 所有内部链接指向存在的页面
-- [ ] Frontmatter 格式正确
-- [ ] 代码块指定了语言
-- [ ] 代码包含中文注释
-- [ ] 文档结构完整
-- [ ] 没有 HTML 标签错误
-
-## 自动修复脚本
-
-如果文档已生成,可以使用以下脚本修复常见问题:
-
-```bash
-# 修复泛型标记
-sed -i 's/<T>/\&lt;T\&gt;/g' file.md
-sed -i 's/<TResult>/\&lt;TResult\&gt;/g' file.md
-sed -i 's/<TValue>/\&lt;TValue\&gt;/g' file.md
-sed -i 's/<TError>/\&lt;TError\&gt;/g' file.md
-
-# 验证构建
-cd docs && bun run build
-```

.claude/skills/_shared/module-config.sh

@@ -1,84 +0,0 @@
-#!/bin/bash
-# 共享的模块配置
-# 用于统一管理 GFramework 项目的模块映射关系
-
-# 根据模块名获取源代码目录
-get_source_dir() {
-    local MODULE="$1"
-    case "$MODULE" in
-        Core)
-            echo "GFramework.Core"
-            ;;
-        Game)
-            echo "GFramework.Game"
-            ;;
-        Godot)
-            echo "GFramework.Godot"
-            ;;
-        SourceGenerators)
-            echo "GFramework.SourceGenerators"
-            ;;
-        *)
-            echo ""
-            return 1
-            ;;
-    esac
-}
-
-# 根据模块名获取文档输出目录
-get_docs_dir() {
-    local MODULE="$1"
-    case "$MODULE" in
-        Core)
-            echo "docs/zh-CN/api-reference/core"
-            ;;
-        Game)
-            echo "docs/zh-CN/api-reference/game"
-            ;;
-        Godot)
-            echo "docs/zh-CN/api-reference/godot"
-            ;;
-        SourceGenerators)
-            echo "docs/zh-CN/api-reference/source-generators"
-            ;;
-        *)
-            echo ""
-            return 1
-            ;;
-    esac
-}
-
-# 根据命名空间推断模块名
-infer_module_from_namespace() {
-    local NAMESPACE="$1"
-    if [[ "$NAMESPACE" == GFramework.Core* ]]; then
-        echo "Core"
-    elif [[ "$NAMESPACE" == GFramework.Game* ]]; then
-        echo "Game"
-    elif [[ "$NAMESPACE" == GFramework.Godot* ]]; then
-        echo "Godot"
-    elif [[ "$NAMESPACE" == GFramework.SourceGenerators* ]]; then
-        echo "SourceGenerators"
-    else
-        echo ""
-        return 1
-    fi
-}
-
-# 获取所有可用模块列表
-get_all_modules() {
-    echo "Core Game Godot SourceGenerators"
-}
-
-# 验证模块名是否有效
-is_valid_module() {
-    local MODULE="$1"
-    case "$MODULE" in
-        Core|Game|Godot|SourceGenerators)
-            return 0
-            ;;
-        *)
-            return 1
-            ;;
-    esac
-}

.claude/skills/vitepress-api-doc/SKILL.md

@@ -1,210 +0,0 @@
-# VitePress API 文档生成
-
-为单个 C# 类、接口或枚举生成符合 VitePress 标准的 API 参考文档。
-
-## 用途
-
-此 skill 用于从 C# 源代码文件自动生成结构化的 API 文档，包括：
-- 类型概述和命名空间信息
-- 构造函数、方法、属性的详细说明
-- 基于 XML 文档注释的描述
-- 自动生成的使用示例
-- 相关类型的交叉引用
-
-## 调用方式
-
-```bash
-/vitepress-api-doc <C# 文件路径>
-```
-
-**示例**：
-```bash
-/vitepress-api-doc GFramework.Core/architecture/Architecture.cs
-```
-
-## 工作流程
-
-1. **读取源代码文件**
-   - 验证文件存在且为 C# 文件
-   - 读取完整的源代码内容
-
-2. **解析代码结构**
-   - 提取命名空间、类名、访问修饰符
-   - 识别类型（class/interface/enum/struct）
-   - 解析继承关系和实现的接口
-   - 提取所有公共成员（构造函数、方法、属性、事件、字段）
-
-3. **提取 XML 文档注释**
-   - 解析 `/// <summary>` 标签（类型和成员描述）
-   - 解析 `/// <param>` 标签（参数说明）
-   - 解析 `/// <returns>` 标签（返回值说明）
-   - 解析 `/// <exception>` 标签（异常说明）
-   - 解析 `/// <example>` 标签（示例代码）
-   - 解析 `/// <see cref=""/>` 标签（交叉引用）
-
-4. **生成 Markdown 文档**
-   - 根据 `template.md` 填充内容
-   - 转义泛型符号（`<T>` → `&lt;T&gt;`）
-   - 生成使用示例（基于 API 签名）
-   - 添加相关文档链接
-
-5. **确定输出路径**
-   - 根据命名空间确定模块（Core/Game/Godot/SourceGenerators）
-   - 输出到 `docs/zh-CN/api-reference/<模块>/<类名>.md`
-
-6. **更新 VitePress 配置**
-   - 调用共享脚本 `update-vitepress-nav.sh`
-   - 在侧边栏配置中添加新文档条目
-
-7. **验证文档质量**
-   - 检查 Frontmatter 格式
-   - 验证内部链接
-   - 确保代码块语法正确
-
-## 输出规范
-
-### Frontmatter 格式
-
-```yaml
----
-title: 类名
-description: 从 XML <summary> 提取的简短描述
-outline: deep
----
-```
-
-### 文档结构
-
-1. **标题**：使用类名作为一级标题
-2. **概述**：XML summary 内容
-3. **命名空间和程序集信息**
-4. **继承链**（如果适用）
-5. **构造函数**（如果有）
-6. **公共方法**（按字母顺序）
-7. **公共属性**（按字母顺序）
-8. **公共事件**（如果有）
-9. **使用示例**（自动生成）
-10. **另请参阅**（相关类型链接）
-
-### 代码块格式
-
-所有 C# 代码块必须使用：
-```markdown
-\`\`\`csharp
-// 代码内容
-\`\`\`
-```
-
-### 泛型符号转义
-
-- `List<T>` → `List&lt;T&gt;`
-- `Dictionary<K, V>` → `Dictionary&lt;K, V&gt;`
-- `IEnumerable<T>` → `IEnumerable&lt;T&gt;`
-
-### 内部链接格式
-
-- 相对路径：`[Architecture](./architecture.md)`
-- 绝对路径：`[Core 架构](/zh-CN/core/architecture)`
-- 锚点链接：`[构造函数](#构造函数)`
-
-## 前置条件
-
-1. 项目必须有 VitePress 配置文件（`docs/.vitepress/config.mts`）
-2. 目标 C# 文件必须存在且可读
-3. C# 文件必须包含 XML 文档注释（`///`）
-4. 文件必须包含至少一个公共类型
-
-## 配置选项
-
-### 自动检测模块
-
-根据命名空间自动确定模块：
-- `GFramework.Core.*` → `core`
-- `GFramework.Game.*` → `game`
-- `GFramework.Godot.*` → `godot`
-- `GFramework.SourceGenerators.*` → `source-generators`
-
-### 示例生成策略
-
-- **基本用法**：最简单的 API 调用
-- **常见场景**：实际应用案例
-- **高级用法**：复杂配置（如果适用）
-
-## 示例输出
-
-参考 `examples/` 目录中的示例文档：
-- `class-example.md` - 类文档示例
-- `interface-example.md` - 接口文档示例
-- `enum-example.md` - 枚举文档示例
-
-## 注意事项
-
-1. **仅使用 XML 注释**：不对缺失的注释进行 AI 补充
-2. **仅提取公共成员**：忽略 `internal`、`private`、`protected` 成员
-3. **保持文档同步**：文档内容直接来源于代码，确保准确性
-4. **遵循项目风格**：参考现有文档的格式和术语
-
-## 相关 Skills
-
-- `/vitepress-validate` - 验证生成的文档质量
-- `/vitepress-batch-api` - 批量生成整个模块的 API 文档
-
-## 技术细节
-
-### XML 注释标签映射
-
-| XML 标签 | Markdown 输出 |
-|---------|--------------|
-| `<summary>` | 概述章节 |
-| `<param name="x">` | 参数列表 |
-| `<returns>` | 返回值说明 |
-| `<exception cref="T">` | 异常列表 |
-| `<example>` | 示例代码块 |
-| `<see cref="T"/>` | 内部链接 |
-| `<remarks>` | 备注章节 |
-
-### 成员签名格式
-
-**方法**：
-```markdown
-### MethodName
-
-描述内容
-
-**签名**：
-\`\`\`csharp
-public ReturnType MethodName(ParamType param)
-\`\`\`
-
-**参数**：
-- `param` (ParamType): 参数说明
-
-**返回值**：
-- (ReturnType): 返回值说明
-```
-
-**属性**：
-```markdown
-### PropertyName
-
-描述内容
-
-**类型**：`PropertyType`
-
-**访问**：get / set
-```
-
-## 故障排除
-
-### 问题：找不到 XML 注释
-**解决方案**：确保 C# 文件包含 `///` 注释，而不是 `//` 或 `/* */`
-
-### 问题：泛型符号显示错误
-**解决方案**：VitePress 配置中已包含 `safeGenericEscapePlugin`，确保正确转义
-
-### 问题：侧边栏未更新
-**解决方案**：检查 `update-vitepress-nav.sh` 脚本是否正确执行
-
-## 版本历史
-
-- v1.0.0 - 初始版本，支持类、接口、枚举的文档生成

.claude/skills/vitepress-api-doc/examples/class-example.md

@@ -1,252 +0,0 @@
----
-title: Architecture
-description: 架构基类，提供系统、模型、工具等组件的注册与管理功能。专注于生命周期管理、初始化流程控制和架构阶段转换。
-outline: deep
----
-
-# Architecture
-
-## 概述
-
-架构基类，提供系统、模型、工具等组件的注册与管理功能。专注于生命周期管理、初始化流程控制和架构阶段转换。
-
-**命名空间**：`GFramework.Core.architecture`
-**程序集**：`GFramework.Core`
-**继承**：`Object` → `Architecture`
-**实现**：`IArchitecture`
-
-## 构造函数
-
-### Architecture
-
-创建架构实例。
-
-**签名**：
-```csharp
-public Architecture(
-    IArchitectureConfiguration? configuration = null,
-    IEnvironment? environment = null,
-    IArchitectureServices? services = null,
-    IArchitectureContext? context = null
-)
-```
-
-**参数**：
-- `configuration` (IArchitectureConfiguration?): 架构配置对象，为 null 时使用默认配置
-- `environment` (IEnvironment?): 环境配置对象，为 null 时使用默认环境
-- `services` (IArchitectureServices?): 架构服务对象，为 null 时创建新实例
-- `context` (IArchitectureContext?): 架构上下文对象，为 null 时创建新实例
-
-## 公共方法
-
-### Initialize
-
-同步初始化架构，阻塞当前线程直到初始化完成。
-
-**签名**：
-```csharp
-public void Initialize()
-```
-
-**特点**：
-- 阻塞式初始化
-- 适用于简单场景或控制台应用
-- 初始化失败时抛出异常并进入 `FailedInitialization` 阶段
-
-### InitializeAsync
-
-异步初始化架构，返回 Task 以便调用者可以等待初始化完成。
-
-**签名**：
-```csharp
-public async Task InitializeAsync()
-```
-
-**返回值**：
-- (Task): 表示异步初始化操作的任务
-
-**特点**：
-- 非阻塞式初始化
-- 支持异步组件初始化
-- 适用于需要异步加载资源的场景
-
-### InstallModule
-
-安装架构模块，用于扩展架构功能。
-
-**签名**：
-```csharp
-public IArchitectureModule InstallModule(IArchitectureModule module)
-```
-
-**参数**：
-- `module` (IArchitectureModule): 要安装的模块实例
-
-**返回值**：
-- (IArchitectureModule): 返回安装的模块实例
-
-### RegisterSystem
-
-注册系统组件到架构中。
-
-**签名**：
-```csharp
-public void RegisterSystem<TSystem>(TSystem system) where TSystem : ISystem
-```
-
-**类型参数**：
-- `TSystem`: 系统类型，必须实现 ISystem 接口
-
-**参数**：
-- `system` (TSystem): 要注册的系统实例
-
-### RegisterModel
-
-注册模型组件到架构中。
-
-**签名**：
-```csharp
-public void RegisterModel<TModel>(TModel model) where TModel : IModel
-```
-
-**类型参数**：
-- `TModel`: 模型类型，必须实现 IModel 接口
-
-**参数**：
-- `model` (TModel): 要注册的模型实例
-
-### RegisterUtility
-
-注册工具组件到架构中。
-
-**签名**：
-```csharp
-public void RegisterUtility<TUtility>(TUtility utility) where TUtility : IUtility
-```
-
-**类型参数**：
-- `TUtility`: 工具类型，必须实现 IUtility 接口
-
-**参数**：
-- `utility` (TUtility): 要注册的工具实例
-
-### SendCommand
-
-发送并执行命令。
-
-**签名**：
-```csharp
-public void SendCommand(ICommand command)
-```
-
-**参数**：
-- `command` (ICommand): 要执行的命令实例
-
-### SendCommand&lt;TResult&gt;
-
-发送并执行带返回值的命令。
-
-**签名**：
-```csharp
-public TResult SendCommand<TResult>(ICommand<TResult> command)
-```
-
-**类型参数**：
-- `TResult`: 命令返回值类型
-
-**参数**：
-- `command` (ICommand&lt;TResult&gt;): 要执行的命令实例
-
-**返回值**：
-- (TResult): 命令执行结果
-
-## 公共属性
-
-### CurrentPhase
-
-获取当前架构的阶段。
-
-**类型**：`ArchitecturePhase`
-**访问**：get
-
-### Context
-
-获取架构上下文，提供对架构服务的访问。
-
-**类型**：`IArchitectureContext`
-**访问**：get
-
-### IsReady
-
-获取一个布尔值，指示当前架构是否处于就绪状态。
-
-**类型**：`bool`
-**访问**：get
-
-## 使用示例
-
-### 基本用法
-
-```csharp
-// 1. 定义你的架构（继承 Architecture 基类）
-public class GameArchitecture : Architecture
-{
-    protected override void Init()
-    {
-        // 注册 Model
-        RegisterModel(new PlayerModel());
-        RegisterModel(new InventoryModel());
-
-        // 注册 System
-        RegisterSystem(new GameplaySystem());
-        RegisterSystem(new SaveSystem());
-
-        // 注册 Utility
-        RegisterUtility(new StorageUtility());
-        RegisterUtility(new TimeUtility());
-    }
-}
-
-// 2. 创建并初始化架构
-var architecture = new GameArchitecture();
-architecture.Initialize();
-
-// 3. 等待架构就绪
-await architecture.WaitUntilReadyAsync();
-```
-
-### 异步初始化
-
-```csharp
-var architecture = new GameArchitecture();
-await architecture.InitializeAsync(); // 异步等待初始化完成
-
-// 检查架构是否已就绪
-if (architecture.IsReady)
-{
-    Console.WriteLine("架构已就绪，可以开始游戏");
-}
-```
-
-### 使用自定义配置
-
-```csharp
-var config = new ArchitectureConfiguration
-{
-    ArchitectureProperties = new ArchitectureProperties
-    {
-        StrictPhaseValidation = true,      // 启用严格阶段验证
-        AllowLateRegistration = false      // 禁止就绪后注册组件
-    }
-};
-
-var architecture = new GameArchitecture(configuration: config);
-architecture.Initialize();
-```
-
-## 另请参阅
-
-- [IArchitecture](./iarchitecture.md) - 架构接口
-- [ArchitecturePhase](./architecture-phase.md) - 架构阶段枚举
-- [IArchitectureModule](./iarchitecture-module.md) - 架构模块接口
-- [架构组件](/zh-CN/core/architecture) - 架构使用指南

.claude/skills/vitepress-api-doc/examples/enum-example.md

@@ -1,193 +0,0 @@
----
-title: ArchitecturePhase
-description: 架构阶段枚举，定义了架构生命周期的各个阶段。
-outline: deep
----
-
-# ArchitecturePhase
-
-## 概述
-
-架构阶段枚举，定义了架构生命周期的各个阶段。
-
-**命名空间**：`GFramework.Core.Abstractions.enums`
-**程序集**：`GFramework.Core.Abstractions`
-**基础类型**：`Enum`
-
-## 枚举值
-
-### None
-
-初始阶段，架构尚未开始初始化。
-
-**值**：`0`
-
-### BeforeUtilityInit
-
-工具初始化前阶段。
-
-**值**：`1`
-
-### AfterUtilityInit
-
-工具初始化后阶段。
-
-**值**：`2`
-
-### BeforeModelInit
-
-模型初始化前阶段。
-
-**值**：`3`
-
-### AfterModelInit
-
-模型初始化后阶段。
-
-**值**：`4`
-
-### BeforeSystemInit
-
-系统初始化前阶段。
-
-**值**：`5`
-
-### AfterSystemInit
-
-系统初始化后阶段。
-
-**值**：`6`
-
-### Ready
-
-就绪状态，架构已完全初始化并可以使用。
-
-**值**：`7`
-
-### FailedInitialization
-
-初始化失败状态。
-
-**值**：`8`
-
-### Destroying
-
-正在销毁阶段。
-
-**值**：`9`
-
-### Destroyed
-
-已销毁阶段。
-
-**值**：`10`
-
-## 使用示例
-
-### 检查架构阶段
-
-```csharp
-var architecture = new GameArchitecture();
-architecture.Initialize();
-
-// 检查架构是否已就绪
-if (architecture.CurrentPhase == ArchitecturePhase.Ready)
-{
-    Console.WriteLine("架构已就绪，可以开始游戏");
-}
-```
-
-### 监听阶段变化
-
-```csharp
-public class PhaseMonitor : IArchitectureLifecycle
-{
-    public void OnPhase(ArchitecturePhase phase, IArchitecture architecture)
-    {
-        switch (phase)
-        {
-            case ArchitecturePhase.BeforeUtilityInit:
-                Console.WriteLine("开始初始化工具");
-                break;
-            case ArchitecturePhase.AfterUtilityInit:
-                Console.WriteLine("工具初始化完成");
-                break;
-            case ArchitecturePhase.BeforeModelInit:
-                Console.WriteLine("开始初始化模型");
-                break;
-            case ArchitecturePhase.AfterModelInit:
-                Console.WriteLine("模型初始化完成");
-                break;
-            case ArchitecturePhase.BeforeSystemInit:
-                Console.WriteLine("开始初始化系统");
-                break;
-            case ArchitecturePhase.AfterSystemInit:
-                Console.WriteLine("系统初始化完成");
-                break;
-            case ArchitecturePhase.Ready:
-                Console.WriteLine("架构就绪");
-                break;
-            case ArchitecturePhase.FailedInitialization:
-                Console.WriteLine("架构初始化失败");
-                break;
-            case ArchitecturePhase.Destroying:
-                Console.WriteLine("架构正在销毁");
-                break;
-            case ArchitecturePhase.Destroyed:
-                Console.WriteLine("架构已销毁");
-                break;
-        }
-    }
-}
-
-// 注册监听器
-var architecture = new GameArchitecture();
-architecture.RegisterLifecycleHook(new PhaseMonitor());
-architecture.Initialize();
-```
-
-### 等待特定阶段
-
-```csharp
-public async Task WaitForReady(IArchitecture architecture)
-{
-    while (architecture.CurrentPhase != ArchitecturePhase.Ready)
-    {
-        if (architecture.CurrentPhase == ArchitecturePhase.FailedInitialization)
-        {
-            throw new Exception("架构初始化失败");
-        }
-
-        await Task.Delay(100);
-    }
-
-    Console.WriteLine("架构已就绪");
-}
-```
-
-## 阶段转换顺序
-
-正常初始化流程的阶段转换顺序：
-
-1. `None` → `BeforeUtilityInit`
-2. `BeforeUtilityInit` → `AfterUtilityInit`
-3. `AfterUtilityInit` → `BeforeModelInit`
-4. `BeforeModelInit` → `AfterModelInit`
-5. `AfterModelInit` → `BeforeSystemInit`
-6. `BeforeSystemInit` → `AfterSystemInit`
-7. `AfterSystemInit` → `Ready`
-
-销毁流程的阶段转换顺序：
-
-1. `Ready` → `Destroying`
-2. `Destroying` → `Destroyed`
-
-异常流程：
-
-- 任何阶段 → `FailedInitialization`（初始化过程中发生异常）
-
-## 另请参阅
-
-- [Architecture](./architecture.md) - 架构基类
-- [IArchitectureLifecycle](./iarchitecture-lifecycle.md) - 生命周期钩子接口
-- [架构组件](/zh-CN/core/architecture) - 架构使用指南

.claude/skills/vitepress-api-doc/examples/interface-example.md

@@ -1,290 +0,0 @@
----
-title: IArchitecture
-description: 架构接口，定义了框架的核心功能契约。
-outline: deep
----
-
-# IArchitecture
-
-## 概述
-
-架构接口，定义了框架的核心功能契约。
-
-**命名空间**：`GFramework.Core.Abstractions.architecture`
-**程序集**：`GFramework.Core.Abstractions`
-**实现类**：[Architecture](./architecture.md)
-
-## 公共方法
-
-### RegisterSystem<TSystem>
-
-注册系统组件到架构中。
-
-**签名**：
-```csharp
-void RegisterSystem<TSystem>(TSystem system) where TSystem : ISystem
-```
-
-**类型参数**：
-- `TSystem`: 系统类型，必须实现 ISystem 接口
-
-**参数**：
-- `system` (TSystem): 要注册的系统实例
-
-### RegisterModel&lt;TModel&gt;
-
-注册模型组件到架构中。
-
-**签名**：
-```csharp
-void RegisterModel<TModel>(TModel model) where TModel : IModel
-```
-
-**类型参数**：
-- `TModel`: 模型类型，必须实现 IModel 接口
-
-**参数**：
-- `model` (TModel): 要注册的模型实例
-
-### RegisterUtility&lt;TUtility&gt;
-
-注册工具组件到架构中。
-
-**签名**：
-```csharp
-void RegisterUtility<TUtility>(TUtility utility) where TUtility : IUtility
-```
-
-**类型参数**：
-- `TUtility`: 工具类型，必须实现 IUtility 接口
-
-**参数**：
-- `utility` (TUtility): 要注册的工具实例
-
-### GetModel&lt;T&gt;
-
-从容器中获取已注册的模型。
-
-**签名**：
-```csharp
-T GetModel<T>() where T : class, IModel
-```
-
-**类型参数**：
-- `T`: 模型类型
-
-**返回值**：
-- (T): 模型实例
-
-### GetSystem&lt;T&gt;
-
-从容器中获取已注册的系统。
-
-**签名**：
-```csharp
-T GetSystem<T>() where T : class, ISystem
-```
-
-**类型参数**：
-- `T`: 系统类型
-
-**返回值**：
-- (T): 系统实例
-
-### GetUtility&lt;T&gt;
-
-从容器中获取已注册的工具。
-
-**签名**：
-```csharp
-T GetUtility<T>() where T : class, IUtility
-```
-
-**类型参数**：
-- `T`: 工具类型
-
-**返回值**：
-- (T): 工具实例
-
-### SendCommand
-
-发送并执行命令。
-
-**签名**：
-```csharp
-void SendCommand(ICommand command)
-```
-
-**参数**：
-- `command` (ICommand): 要执行的命令实例
-
-### SendCommand&lt;TResult&gt;
-
-发送并执行带返回值的命令。
-
-**签名**：
-```csharp
-TResult SendCommand<TResult>(ICommand<TResult> command)
-```
-
-**类型参数**：
-- `TResult`: 命令返回值类型
-
-**参数**：
-- `command` (ICommand&lt;TResult&gt;): 要执行的命令实例
-
-**返回值**：
-- (TResult): 命令执行结果
-
-### SendQuery&lt;TResult&gt;
-
-发送并执行查询。
-
-**签名**：
-```csharp
-TResult SendQuery<TResult>(IQuery<TResult> query)
-```
-
-**类型参数**：
-- `TResult`: 查询返回值类型
-
-**参数**：
-- `query` (IQuery&lt;TResult&gt;): 要执行的查询实例
-
-**返回值**：
-- (TResult): 查询结果
-
-### SendEvent&lt;T&gt;
-
-发送事件（无参数）。
-
-**签名**：
-```csharp
-void SendEvent<T>() where T : new()
-```
-
-**类型参数**：
-- `T`: 事件类型，必须有无参构造函数
-
-### SendEvent&lt;T&gt;
-
-发送事件（带参数）。
-
-**签名**：
-```csharp
-void SendEvent<T>(T e)
-```
-
-**类型参数**：
-- `T`: 事件类型
-
-**参数**：
-- `e` (T): 事件实例
-
-### RegisterEvent&lt;T&gt;
-
-注册事件监听器。
-
-**签名**：
-```csharp
-IUnRegister RegisterEvent<T>(Action<T> onEvent)
-```
-
-**类型参数**：
-- `T`: 事件类型
-
-**参数**：
-- `onEvent` (Action&lt;T&gt;): 事件处理回调
-
-**返回值**：
-- (IUnRegister): 用于注销事件的对象
-
-### UnRegisterEvent&lt;T&gt;
-
-注销事件监听器。
-
-**签名**：
-```csharp
-void UnRegisterEvent<T>(Action<T> onEvent)
-```
-
-**类型参数**：
-- `T`: 事件类型
-
-**参数**：
-- `onEvent` (Action&lt;T&gt;): 要注销的事件处理回调
-
-## 公共属性
-
-### CurrentPhase
-
-获取当前架构的阶段。
-
-**类型**：`ArchitecturePhase`
-**访问**：get
-
-### Context
-
-获取架构上下文。
-
-**类型**：`IArchitectureContext`
-**访问**：get
-
-## 使用示例
-
-### 在 Controller 中使用
-
-```csharp
-public class GameController : IController
-{
-    public IArchitecture GetArchitecture() => GameArchitecture.Interface;
-
-    public void Start()
-    {
-        // 获取 Model
-        var playerModel = this.GetModel<PlayerModel>();
-
-        // 发送命令
-        this.SendCommand(new StartGameCommand());
-
-        // 发送查询
-        var score = this.SendQuery(new GetScoreQuery());
-
-        // 注册事件
-        this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);
-    }
-
-    private void OnPlayerDied(PlayerDiedEvent e)
-    {
-        // 处理玩家死亡事件
-    }
-}
-```
-
-### 实现自定义架构
-
-```csharp
-public class GameArchitecture : Architecture
-{
-    // 单例访问
-    public static IArchitecture Interface { get; private set; }
-
-    protected override void Init()
-    {
-        Interface = this;
-
-        // 注册组件
-        RegisterModel(new PlayerModel());
-        RegisterSystem(new GameplaySystem());
-        RegisterUtility(new StorageUtility());
-    }
-}
-```
-
-## 另请参阅
-
-- [Architecture](./architecture.md) - 架构基类实现
-- [IModel](./imodel.md) - 模型接口
-- [ISystem](./isystem.md) - 系统接口
-- [IUtility](./iutility.md) - 工具接口
-- [架构组件](/zh-CN/core/architecture) - 架构使用指南

.claude/skills/vitepress-api-doc/template.md

@@ -1,37 +0,0 @@
----
-title: {{CLASS_NAME}}
-description: {{XML_SUMMARY}}
-outline: deep
----
-
-# {{CLASS_NAME}}
-
-## 概述
-
-{{XML_SUMMARY}}
-
-**命名空间**：`{{NAMESPACE}}`
-**程序集**：`{{ASSEMBLY}}`
-{{INHERITANCE_CHAIN}}
-
-## 构造函数
-
-{{CONSTRUCTORS}}
-
-## 公共方法
-
-{{PUBLIC_METHODS}}
-
-## 公共属性
-
-{{PUBLIC_PROPERTIES}}
-
-{{PUBLIC_EVENTS}}
-
-## 使用示例
-
-{{AUTO_GENERATED_EXAMPLES}}
-
-## 另请参阅
-
-{{RELATED_TYPES}}

.claude/skills/vitepress-batch-api/SKILL.md

@@ -1,364 +0,0 @@
-# VitePress 批量 API 文档生成
-
-为整个模块批量生成 API 参考文档，提高文档生成效率。
-
-## 用途
-
-此 skill 用于批量生成模块的 API 文档，适用于：
-- 初始化模块文档
-- 更新整个模块的文档
-- 为新模块快速生成文档
-- 重新生成所有 API 文档
-
-## 调用方式
-
-```bash
-/vitepress-batch-api <模块名>
-```
-
-**示例**：
-```bash
-/vitepress-batch-api Core
-/vitepress-batch-api Game
-/vitepress-batch-api Godot
-/vitepress-batch-api SourceGenerators
-```
-
-## 工作流程
-
-1. **扫描模块目录**
-   - 根据模块名确定源代码目录
-   - 递归扫描所有 C# 文件
-
-2. **过滤目标文件**
-   - 仅包含公共类型（public class/interface/enum/struct）
-   - 排除内部类型（internal）
-   - 排除生成的代码（*.g.cs、*.Designer.cs）
-   - 排除测试文件（*.Tests.cs）
-
-3. **批量生成文档**
-   - 为每个类型调用 `/vitepress-api-doc`
-   - 显示进度信息
-   - 收集生成结果
-
-4. **生成模块索引页**
-   - 创建 `index.md` 列出所有 API
-   - 按类别分组（类、接口、枚举）
-   - 添加简短描述
-
-5. **批量更新导航**
-   - 在 VitePress 配置中添加所有新文档
-   - 保持字母顺序
-   - 更新模块索引
-
-6. **生成摘要报告**
-   - 统计生成的文档数量
-   - 列出成功和失败的文件
-   - 提供验证建议
-
-## 输出规范
-
-### 模块索引页格式
-
-```markdown
----
-title: Core API 参考
-description: GFramework.Core 模块的 API 参考文档
----
-
-# Core API 参考
-
-## 概述
-
-GFramework.Core 是框架的核心模块，提供架构基础、依赖注入、事件系统等核心功能。
-
-## 类
-
-- [Architecture](./architecture.md) - 架构基类
-- [ArchitectureConfiguration](./architecture-configuration.md) - 架构配置
-- [IocContainer](./ioc-container.md) - IoC 容器
-
-## 接口
-
-- [IArchitecture](./iarchitecture.md) - 架构接口
-- [IModel](./imodel.md) - 模型接口
-- [ISystem](./isystem.md) - 系统接口
-
-## 枚举
-
-- [ArchitecturePhase](./architecture-phase.md) - 架构阶段
-```
-
-### 目录结构
-
-```
-docs/zh-CN/api-reference/
-├── core/
-│   ├── index.md              # 模块索引
-│   ├── architecture.md
-│   ├── iarchitecture.md
-│   └── ...
-├── game/
-│   ├── index.md
-│   └── ...
-└── godot/
-    ├── index.md
-    └── ...
-```
-
-## 模块映射
-
-### 源代码目录映射
-
-| 模块名 | 源代码目录 | 输出目录 |
-|--------|-----------|---------|
-| Core | `GFramework.Core/` | `docs/zh-CN/api-reference/core/` |
-| Game | `GFramework.Game/` | `docs/zh-CN/api-reference/game/` |
-| Godot | `GFramework.Godot/` | `docs/zh-CN/api-reference/godot/` |
-| SourceGenerators | `GFramework.SourceGenerators/` | `docs/zh-CN/api-reference/source-generators/` |
-
-### 命名空间映射
-
-- `GFramework.Core.*` → Core 模块
-- `GFramework.Game.*` → Game 模块
-- `GFramework.Godot.*` → Godot 模块
-- `GFramework.SourceGenerators.*` → SourceGenerators 模块
-
-## 过滤规则
-
-### 包含的文件
-
-- 公共类（public class）
-- 公共接口（public interface）
-- 公共枚举（public enum）
-- 公共结构体（public struct）
-
-### 排除的文件
-
-- 内部类型（internal）
-- 生成的代码（`*.g.cs`、`*.Designer.cs`）
-- 测试文件（`*.Tests.cs`、`*Test.cs`）
-- 临时文件（`*.tmp.cs`）
-- 编译器生成的文件（`AssemblyInfo.cs`）
-
-### 排除的类型
-
-- 编译器生成的类型（`<>c__DisplayClass`）
-- 匿名类型
-- 嵌套的私有类型
-
-## 批量处理脚本
-
-### batch-generate.sh
-
-```bash
-#!/bin/bash
-# 批量生成 API 文档
-# 用法: batch-generate.sh <模块名>
-
-set -e
-
-MODULE="$1"
-
-if [ -z "$MODULE" ]; then
-    echo "用法: $0 <模块名>"
-    echo "可用模块: Core, Game, Godot, SourceGenerators"
-    exit 1
-fi
-
-# 确定源代码目录
-case "$MODULE" in
-    Core)
-        SOURCE_DIR="GFramework.Core"
-        ;;
-    Game)
-        SOURCE_DIR="GFramework.Game"
-        ;;
-    Godot)
-        SOURCE_DIR="GFramework.Godot"
-        ;;
-    SourceGenerators)
-        SOURCE_DIR="GFramework.SourceGenerators"
-        ;;
-    *)
-        echo "错误: 未知的模块: $MODULE"
-        exit 1
-        ;;
-esac
-
-if [ ! -d "$SOURCE_DIR" ]; then
-    echo "错误: 源代码目录不存在: $SOURCE_DIR"
-    exit 1
-fi
-
-echo "=========================================="
-echo "批量生成 $MODULE 模块的 API 文档"
-echo "=========================================="
-echo ""
-
-# 查找所有 C# 文件
-FILES=$(find "$SOURCE_DIR" -name "*.cs" -type f \
-    ! -name "*.g.cs" \
-    ! -name "*.Designer.cs" \
-    ! -name "*Test.cs" \
-    ! -name "*.Tests.cs" \
-    ! -name "AssemblyInfo.cs")
-
-FILE_COUNT=$(echo "$FILES" | wc -l)
-echo "找到 $FILE_COUNT 个文件"
-echo ""
-
-GENERATED=0
-SKIPPED=0
-FAILED=0
-
-for FILE in $FILES; do
-    echo "处理: $FILE"
-
-    # 检查是否包含公共类型
-    if ! grep -q "public \(class\|interface\|enum\|struct\)" "$FILE"; then
-        echo "  ⊘ 跳过（无公共类型）"
-        SKIPPED=$((SKIPPED + 1))
-        continue
-    fi
-
-    # 调用 vitepress-api-doc（由 AI 执行）
-    # /vitepress-api-doc "$FILE"
-
-    if [ $? -eq 0 ]; then
-        echo "  ✓ 生成成功"
-        GENERATED=$((GENERATED + 1))
-    else
-        echo "  ✗ 生成失败"
-        FAILED=$((FAILED + 1))
-    fi
-
-    echo ""
-done
-
-echo "=========================================="
-echo "批量生成完成"
-echo "=========================================="
-echo "总文件数: $FILE_COUNT"
-echo "生成成功: $GENERATED"
-echo "跳过: $SKIPPED"
-echo "失败: $FAILED"
-echo ""
-
-if [ $FAILED -eq 0 ]; then
-    echo "✓ 所有文档生成成功"
-    exit 0
-else
-    echo "✗ 部分文档生成失败"
-    exit 1
-fi
-```
-
-## 配置选项
-
-### 过滤选项
-
-```bash
-# 包含内部类型
-/vitepress-batch-api Core --include-internal
-
-# 包含生成的代码
-/vitepress-batch-api Core --include-generated
-
-# 自定义过滤规则
-/vitepress-batch-api Core --exclude "*.Tests.cs" --exclude "*.g.cs"
-```
-
-### 输出选项
-
-```bash
-# 指定输出目录
-/vitepress-batch-api Core --output docs/zh-CN/api-reference/core/
-
-# 覆盖现有文档
-/vitepress-batch-api Core --force
-
-# 仅生成索引页
-/vitepress-batch-api Core --index-only
-```
-
-### 并行处理
-
-```bash
-# 并行生成（加快速度）
-/vitepress-batch-api Core --parallel 4
-```
-
-## 进度显示
-
-### 实时进度
-
-```
-========================================
-批量生成 Core 模块的 API 文档
-========================================
-
-找到 45 个文件
-
-[1/45] 处理: GFramework.Core/architecture/Architecture.cs
-  ✓ 生成成功
-
-[2/45] 处理: GFramework.Core/architecture/IArchitecture.cs
-  ✓ 生成成功
-
-[3/45] 处理: GFramework.Core/command/Command.cs
-  ⊘ 跳过（无公共类型）
-
-...
-
-[45/45] 处理: GFramework.Core/utility/Utility.cs
-  ✓ 生成成功
-
-========================================
-批量生成完成
-========================================
-总文件数: 45
-生成成功: 38
-跳过: 5
-失败: 2
-
-✗ 部分文档生成失败
-
-失败的文件:
-- GFramework.Core/internal/InternalClass.cs (缺少 XML 注释)
-- GFramework.Core/legacy/LegacyClass.cs (解析错误)
-```
-
-## 前置条件
-
-1. 模块源代码目录存在
-2. 源代码文件包含 XML 文档注释
-3. 有足够的磁盘空间存储生成的文档
-
-## 相关 Skills
-
-- `/vitepress-api-doc` - 单文件 API 文档生成
-- `/vitepress-validate` - 验证生成的文档
-- `/vitepress-guide` - 生成功能指南
-
-## 最佳实践
-
-1. **首次生成**：使用批量生成快速创建所有文档
-2. **增量更新**：修改代码后使用单文件生成更新对应文档
-3. **定期验证**：批量生成后运行验证确保质量
-4. **版本控制**：将生成的文档提交到版本控制系统
-
-## 故障排除
-
-### 问题：部分文件生成失败
-**解决方案**：检查失败文件的 XML 注释是否完整，手动修复后重新生成
-
-### 问题：生成速度慢
-**解决方案**：使用 `--parallel` 选项启用并行处理
-
-### 问题：生成的文档过多
-**解决方案**：使用过滤选项排除不需要的文件
-
-## 版本历史
-
-- v1.0.0 - 初始版本，支持批量 API 文档生成

.claude/skills/vitepress-batch-api/scripts/batch-generate.sh

@@ -1,81 +0,0 @@
-#!/bin/bash
-# 批量生成 API 文档
-# 用法: batch-generate.sh <模块名>
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=../../_shared/module-config.sh
-source "$SCRIPT_DIR/../../_shared/module-config.sh"
-
-MODULE="$1"
-
-if [ -z "$MODULE" ]; then
-    echo "用法: $0 <模块名>"
-    echo "可用模块: $(get_all_modules)"
-    exit 1
-fi
-
-# 验证模块名
-if ! is_valid_module "$MODULE"; then
-    echo "错误: 未知的模块: $MODULE"
-    echo "可用模块: $(get_all_modules)"
-    exit 1
-fi
-
-# 获取源代码目录
-SOURCE_DIR=$(get_source_dir "$MODULE")
-
-if [ ! -d "$SOURCE_DIR" ]; then
-    echo "错误: 源代码目录不存在: $SOURCE_DIR"
-    exit 1
-fi
-
-echo "=========================================="
-echo "批量生成 $MODULE 模块的 API 文档"
-echo "=========================================="
-echo ""
-
-# 查找所有 C# 文件
-mapfile -t FILES < <(find "$SOURCE_DIR" -name "*.cs" -type f \
-    ! -name "*.g.cs" \
-    ! -name "*.Designer.cs" \
-    ! -name "*Test.cs" \
-    ! -name "*.Tests.cs" \
-    ! -name "AssemblyInfo.cs")
-
-FILE_COUNT=${#FILES[@]}
-echo "找到 $FILE_COUNT 个文件"
-echo ""
-
-GENERATED=0
-SKIPPED=0
-FAILED=0
-
-for FILE in "${FILES[@]}"; do
-    echo "处理: $FILE"
-
-    # 检查是否包含公共类型
-    if ! grep -q "public \(class\|interface\|enum\|struct\)" "$FILE"; then
-        echo "  ⊘ 跳过（无公共类型）"
-        SKIPPED=$((SKIPPED + 1))
-        continue
-    fi
-
-    # 注意: 实际的文档生成由 AI 调用 /vitepress-api-doc 完成
-    # 此脚本仅用于扫描和过滤文件
-
-    echo "  → 待生成"
-    GENERATED=$((GENERATED + 1))
-    echo ""
-done
-
-echo "=========================================="
-echo "扫描完成"
-echo "=========================================="
-echo "总文件数: $FILE_COUNT"
-echo "待生成: $GENERATED"
-echo "跳过: $SKIPPED"
-echo ""
-
-exit 0

.claude/skills/vitepress-doc-generator/SKILL.md

@@ -1,52 +0,0 @@
----
-name: vitepress-doc-generator
-description: Generate standardized VitePress documentation from source code.
-disable-model-invocation: true
----
-
-# Role
-
-You are a technical documentation generator specialized in VitePress.
-
-# Objective
-
-Analyze the provided code context and generate a structured VitePress-compatible Markdown document.
-
-# Output Requirements
-
-1. Output MUST be valid Markdown only.
-2. Include frontmatter:
-
----
-title: <Module Name>
-outline: deep
----
-
-3. No explanations.
-4. No conversational text.
-5. No emoji.
-6. Use Chinese.
-7. Use structured headings.
-
-# Required Structure
-
-# 模块概述
-- 模块职责
-- 设计目标
-
-# 核心类说明
-## 类名
-### 职责
-### 主要方法
-### 依赖关系
-
-# 设计模式分析
-# 可扩展性说明
-# 使用示例（如适用）
-
-# Self-Validation
-
-Before returning output, verify:
-- Frontmatter exists
-- All required sections exist
-- No extra commentary text

.claude/skills/vitepress-guide/SKILL.md

@@ -1,256 +0,0 @@
-# VitePress 功能指南生成
-
-生成功能模块的使用指南文档，包括概念说明、用法示例和最佳实践。
-
-## 用途
-
-此 skill 用于生成结构化的功能指南文档，适用于：
-- 核心功能模块的使用说明
-- 设计模式和架构概念
-- 系统功能的详细介绍
-- 最佳实践和常见问题
-
-## 调用方式
-
-```bash
-/vitepress-guide <主题> <目标模块>
-```
-
-**示例**：
-```bash
-/vitepress-guide "事件系统" Core
-/vitepress-guide "IoC 容器" Core
-/vitepress-guide "Godot 节点扩展" Godot
-```
-
-## 工作流程
-
-1. **收集需求**
-   - 询问用户指南主题
-   - 确定目标受众（初学者/进阶/专家）
-   - 了解重点内容（概念/用法/最佳实践）
-
-2. **搜索相关资源**
-   - 搜索相关代码文件
-   - 查找现有文档
-   - 识别相关类型和接口
-
-3. **生成指南结构**
-   - 根据 `template.md` 创建文档框架
-   - 填充概述和核心概念
-   - 添加基本用法和高级用法
-   - 补充最佳实践和常见问题
-
-4. **生成代码示例**
-   - 基本用法示例（最简单的场景）
-   - 常见场景示例（实际应用）
-   - 高级用法示例（复杂配置）
-
-5. **确定输出路径**
-   - 保存到 `docs/zh-CN/<模块>/`
-   - 文件名使用小写加连字符（如 `event-system.md`）
-
-6. **更新导航配置**
-   - 在 VitePress 侧边栏中添加新指南
-
-## 输出规范
-
-### Frontmatter 格式
-
-```yaml
----
-title: 指南标题
-description: 简短描述（1-2 句话）
----
-```
-
-### 文档结构
-
-1. **概述**：功能的简介和用途
-2. **核心概念**：关键概念和术语解释
-3. **基本用法**：最简单的使用方式
-4. **高级用法**：复杂场景和配置
-5. **最佳实践**：推荐的使用方式
-6. **常见问题**：FAQ 和故障排除
-
-### 章节示例
-
-**概述**：
-```markdown
-## 概述
-
-事件系统提供了一种松耦合的组件间通信机制。通过事件，不同的组件可以在不直接引用彼此的情况下进行交互。
-
-**主要特性**：
-- 类型安全的事件
-- 自动内存管理
-- 支持事件优先级
-- 线程安全
-```
-
-**核心概念**：
-```markdown
-## 核心概念
-
-### 事件类型
-
-事件是一个普通的 C# 类，用于携带事件数据：
-
-\`\`\`csharp
-public class PlayerDiedEvent
-{
-    public int PlayerId { get; set; }
-    public string Reason { get; set; }
-}
-\`\`\`
-
-### 事件发送
-
-通过架构发送事件：
-
-\`\`\`csharp
-this.SendEvent(new PlayerDiedEvent
-{
-    PlayerId = 1,
-    Reason = "Fall damage"
-});
-\`\`\`
-
-### 事件监听
-
-注册事件监听器：
-
-\`\`\`csharp
-this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);
-\`\`\`
-```
-
-## 模板变量
-
-- `{{GUIDE_TITLE}}` - 指南标题
-- `{{GUIDE_DESCRIPTION}}` - 简短描述
-- `{{OVERVIEW}}` - 概述内容
-- `{{CORE_CONCEPTS}}` - 核心概念
-- `{{BASIC_USAGE}}` - 基本用法
-- `{{ADVANCED_USAGE}}` - 高级用法
-- `{{BEST_PRACTICES}}` - 最佳实践
-- `{{FAQ}}` - 常见问题
-
-## 示例输出
-
-参考 `examples/guide-example.md`，该示例基于现有的 IoC 容器文档创建。
-
-## 内容要求
-
-### 概述部分
-- 1-2 段简介
-- 列出主要特性（3-5 个）
-- 说明适用场景
-
-### 核心概念部分
-- 使用三级标题（###）分隔不同概念
-- 每个概念包含简短说明和代码示例
-- 解释关键术语
-
-### 基本用法部分
-- 提供完整的可运行示例
-- 从最简单的场景开始
-- 逐步增加复杂度
-- 包含必要的 using 语句
-
-### 高级用法部分
-- 展示复杂场景
-- 说明配置选项
-- 提供性能优化建议
-
-### 最佳实践部分
-- 使用编号列表
-- 每条实践包含简短说明
-- 提供正反示例（✓ 推荐 / ✗ 不推荐）
-
-### 常见问题部分
-- 使用问答格式
-- 提供具体的解决方案
-- 包含相关链接
-
-## 写作风格
-
-### 语气
-- 友好、专业
-- 使用第二人称（"你"）
-- 避免过于技术化的术语
-
-### 代码示例
-- 完整且可运行
-- 包含注释说明关键步骤
-- 使用有意义的变量名
-- 遵循项目代码风格
-
-### 格式
-- 使用 Markdown 标准格式
-- 代码块使用语法高亮
-- 重要内容使用粗体或引用块
-- 适当使用列表和表格
-
-## 配置选项
-
-### 目标受众
-
-```bash
-# 初学者（更多解释，简单示例）
-/vitepress-guide "事件系统" Core --audience beginner
-
-# 进阶（平衡解释和示例）
-/vitepress-guide "事件系统" Core --audience intermediate
-
-# 专家（简洁说明，复杂示例）
-/vitepress-guide "事件系统" Core --audience expert
-```
-
-### 重点内容
-
-```bash
-# 侧重概念
-/vitepress-guide "事件系统" Core --focus concepts
-
-# 侧重用法
-/vitepress-guide "事件系统" Core --focus usage
-
-# 侧重最佳实践
-/vitepress-guide "事件系统" Core --focus best-practices
-```
-
-## 前置条件
-
-1. 了解指南主题的基本概念
-2. 能够访问相关代码文件
-3. 了解项目的代码风格和术语
-
-## 相关 Skills
-
-- `/vitepress-api-doc` - 生成 API 参考文档
-- `/vitepress-tutorial` - 生成分步教程
-- `/vitepress-validate` - 验证生成的文档
-
-## 最佳实践
-
-1. **先搜索后编写**：查看现有文档和代码，保持一致性
-2. **使用真实示例**：基于项目实际代码创建示例
-3. **保持简洁**：每个章节聚焦一个主题
-4. **提供完整代码**：确保示例可以直接运行
-5. **添加交叉引用**：链接到相关的 API 文档和其他指南
-
-## 故障排除
-
-### 问题：不确定指南应该包含哪些内容
-**解决方案**：参考 `examples/guide-example.md` 和现有的指南文档
-
-### 问题：代码示例过于复杂
-**解决方案**：将复杂示例拆分为多个简单示例，逐步增加复杂度
-
-### 问题：概念解释不清晰
-**解决方案**：使用类比、图表或分步说明来辅助解释
-
-## 版本历史
-
-- v1.0.0 - 初始版本，支持功能指南生成

.claude/skills/vitepress-guide/examples/guide-example.md

@@ -1,283 +0,0 @@
----
-title: IoC 容器使用指南
-description: IoC（控制反转）容器提供了轻量级的依赖注入功能，用于管理框架中各种组件的注册和获取。
----
-
-# IoC 容器使用指南
-
-## 概述
-
-IoC（Inversion of Control，控制反转）包提供了一个轻量级的依赖注入容器，用于管理框架中各种组件的注册和获取。通过 IoC 容器，可以实现组件间的解耦，便于测试和维护。
-
-IoC 容器是 GFramework 架构的核心组件之一，为整个框架提供依赖管理和组件解析服务。
-
-**主要特性**：
-- 类型安全的依赖管理
-- 支持单例和多实例注册
-- 线程安全操作
-- 容器冻结保护
-- 自动接口注册
-
-## 核心概念
-
-### 依赖注入
-
-依赖注入是一种设计模式，通过容器管理对象的创建和依赖关系，而不是在代码中直接创建对象。
-
-```csharp
-// 不使用依赖注入
-public class GameController
-{
-    private PlayerModel model = new PlayerModel(); // 硬编码依赖
-}
-
-// 使用依赖注入
-public class GameController : IController
-{
-    public IArchitecture GetArchitecture() => GameArchitecture.Interface;
-
-    public void Start()
-    {
-        var model = this.GetModel<PlayerModel>(); // 从容器获取
-    }
-}
-```
-
-### 容器注册
-
-在架构初始化时，将组件注册到容器中：
-
-```csharp
-public class GameArchitecture : Architecture
-{
-    protected override void Init()
-    {
-        // 注册 Model
-        RegisterModel(new PlayerModel());
-
-        // 注册 System
-        RegisterSystem(new GameplaySystem());
-
-        // 注册 Utility
-        RegisterUtility(new StorageUtility());
-    }
-}
-```
-
-### 容器解析
-
-通过扩展方法从容器中获取已注册的组件：
-
-```csharp
-// 在 Controller 中
-var playerModel = this.GetModel<PlayerModel>();
-var gameplaySystem = this.GetSystem<GameplaySystem>();
-var storageUtility = this.GetUtility<StorageUtility>();
-```
-
-## 基本用法
-
-### 注册组件
-
-```csharp
-var container = new IocContainer();
-
-// 注册单例（一个类型只能有一个实例）
-container.RegisterSingleton<IPlayerModel>(new PlayerModel());
-
-// 注册多实例（一个类型可以有多个实例）
-container.RegisterPlurality<IEnemy>(new Goblin());
-container.RegisterPlurality<IEnemy>(new Orc());
-container.RegisterPlurality<IEnemy>(new Dragon());
-```
-
-### 获取组件
-
-```csharp
-// 获取单例
-var playerModel = container.Get<IPlayerModel>();
-
-// 获取多实例集合
-var enemies = container.GetAll<IEnemy>(); // 返回 List<IEnemy>
-```
-
-### 在架构中使用
-
-```csharp
-public class GameArchitecture : Architecture
-{
-    protected override void Init()
-    {
-        // 注册组件
-        RegisterModel(new PlayerModel());
-        RegisterModel(new InventoryModel());
-        RegisterSystem(new GameplaySystem());
-    }
-}
-
-// 在 Controller 中使用
-public class GameController : IController
-{
-    public IArchitecture GetArchitecture() => GameArchitecture.Interface;
-
-    public void Start()
-    {
-        // 通过扩展方法获取组件
-        var playerModel = this.GetModel<PlayerModel>();
-        var inventoryModel = this.GetModel<InventoryModel>();
-        var gameplaySystem = this.GetSystem<GameplaySystem>();
-    }
-}
-```
-
-## 高级用法
-
-### 容器冻结
-
-容器在架构初始化完成后会被冻结，防止运行时修改：
-
-```csharp
-var container = new IocContainer();
-container.Register<IPlayerModel>(new PlayerModel());
-
-// 冻结容器
-container.Freeze();
-
-// 以下操作会抛出 InvalidOperationException
-// container.Register<IGameSystem>(new GameSystem());
-```
-
-### 多实例管理
-
-```csharp
-// 注册多个同类型实例
-container.RegisterPlurality<IWeapon>(new Sword());
-container.RegisterPlurality<IWeapon>(new Bow());
-container.RegisterPlurality<IWeapon>(new Staff());
-
-// 获取所有实例
-var allWeapons = container.GetAll<IWeapon>();
-foreach (var weapon in allWeapons)
-{
-    weapon.Attack();
-}
-```
-
-### 接口自动注册
-
-注册实例时，容器会自动将其注册到所有实现的接口：
-
-```csharp
-public class PlayerModel : IModel, IPlayerModel, IDisposable
-{
-    // ...
-}
-
-// 注册实例
-container.Register<PlayerModel>(new PlayerModel());
-
-// 可以通过任何接口获取
-var model1 = container.Get<IModel>();
-var model2 = container.Get<IPlayerModel>();
-var model3 = container.Get<IDisposable>();
-// 以上三个变量指向同一个实例
-```
-
-### 线程安全操作
-
-容器的所有操作都是线程安全的：
-
-```csharp
-// 多线程环境下安全使用
-Parallel.For(0, 100, i =>
-{
-    var model = container.Get<IPlayerModel>();
-    model.DoSomething();
-});
-```
-
-## 最佳实践
-
-1. **使用接口注册**：优先使用接口类型注册，而不是具体类型
-   ```csharp
-   ✓ container.Register<IPlayerModel>(new PlayerModel());
-   ✗ container.Register<PlayerModel>(new PlayerModel());
-   ```
-
-2. **单例 vs 多实例**：根据需求选择合适的注册方式
-   - 单例：全局唯一的服务（如配置、管理器）
-   - 多实例：可以有多个实例的对象（如敌人、道具）
-
-3. **避免循环依赖**：组件之间不应该相互依赖
-   ```csharp
-   ✗ System A 依赖 System B，System B 又依赖 System A
-   ✓ 使用事件系统进行通信，避免直接依赖
-   ```
-
-4. **在 Init 中注册**：所有组件应该在架构的 `Init()` 方法中注册
-   ```csharp
-   protected override void Init()
-   {
-       // 在这里注册所有组件
-       RegisterModel(new PlayerModel());
-       RegisterSystem(new GameplaySystem());
-   }
-   ```
-
-5. **使用扩展方法**：通过扩展方法获取组件，代码更简洁
-   ```csharp
-   ✓ var model = this.GetModel<PlayerModel>();
-   ✗ var model = this.GetArchitecture().GetModel<PlayerModel>();
-   ```
-
-6. **不要在运行时注册**：容器冻结后不应该再注册新组件
-   ```csharp
-   ✗ 在游戏运行时动态注册组件
-   ✓ 在架构初始化时注册所有需要的组件
-   ```
-
-## 常见问题
-
-### 问题：如何判断使用单例还是多实例？
-
-**解答**：
-- 使用单例（`RegisterSingleton`）：全局唯一的服务，如 PlayerModel、GameConfiguration
-- 使用多实例（`RegisterPlurality`）：可以有多个实例的对象，如 Enemy、Weapon
-
-### 问题：容器冻结后如何添加新组件？
-
-**解答**：
-容器冻结是为了保护架构稳定性。如果需要动态添加组件，应该：
-1. 在架构初始化时预先注册所有可能需要的组件
-2. 使用对象池模式管理动态对象
-3. 考虑使用工厂模式创建临时对象
-
-### 问题：如何处理组件的生命周期？
-
-**解答**：
-- 实现 `IDisposable` 接口的组件会在架构销毁时自动释放
-- 架构会按注册的逆序销毁组件
-- 不需要手动管理组件的生命周期
-
-### 问题：可以在容器中注册值类型吗？
-
-**解答**：
-可以，但会发生装箱。建议将值类型包装在类中：
-```csharp
-// 不推荐
-container.Register<int>(42);
-
-// 推荐
-public class GameConfig
-{
-    public int MaxPlayers { get; set; } = 42;
-}
-container.Register<GameConfig>(new GameConfig());
-```
-
-## 相关文档
-
-- [架构组件](/zh-CN/core/architecture) - 架构基础
-- [Model 层](/zh-CN/core/model) - 数据模型
-- [System 层](/zh-CN/core/system) - 业务系统
-- [Utility 工具类](/zh-CN/core/utility) - 工具类

.claude/skills/vitepress-guide/template.md

@@ -1,34 +0,0 @@
----
-title: {{GUIDE_TITLE}}
-description: {{GUIDE_DESCRIPTION}}
----
-
-# {{GUIDE_TITLE}}
-
-## 概述
-
-{{OVERVIEW}}
-
-## 核心概念
-
-{{CORE_CONCEPTS}}
-
-## 基本用法
-
-{{BASIC_USAGE}}
-
-## 高级用法
-
-{{ADVANCED_USAGE}}
-
-## 最佳实践
-
-{{BEST_PRACTICES}}
-
-## 常见问题
-
-{{FAQ}}
-
-## 相关文档
-
-{{RELATED_DOCS}}

.claude/skills/vitepress-tutorial/SKILL.md

@@ -1,253 +0,0 @@
-# VitePress 教程生成
-
-生成分步教程文档，适合初学者学习框架功能。
-
-## 用途
-
-此 skill 用于生成结构化的分步教程，适用于：
-- 框架入门教程
-- 功能实现教程
-- 最佳实践演示
-- 问题解决方案
-
-## 调用方式
-
-```bash
-/vitepress-tutorial <教程主题>
-```
-
-**示例**：
-```bash
-/vitepress-tutorial "创建第一个 System"
-/vitepress-tutorial "实现自定义命令"
-/vitepress-tutorial "使用事件系统"
-```
-
-## 工作流程
-
-1. **收集需求**
-   - 询问用户教程主题
-   - 确定学习目标
-   - 了解前置知识要求
-
-2. **设计教程步骤**
-   - 将任务分解为 3-7 个步骤
-   - 每步聚焦一个具体任务
-   - 确保步骤之间逻辑连贯
-
-3. **生成教程内容**
-   - 根据 `template.md` 创建文档框架
-   - 为每步编写详细说明和代码
-   - 添加完整的可运行代码
-   - 说明预期结果
-
-4. **确定输出路径**
-   - 保存到 `docs/zh-CN/tutorials/`
-   - 文件名使用小写加连字符
-
-5. **更新导航配置**
-   - 在 VitePress 侧边栏中添加新教程
-
-## 输出规范
-
-### Frontmatter 格式
-
-```yaml
----
-title: 教程标题
-description: 简短描述（1 句话说明学习内容）
----
-```
-
-### 文档结构
-
-1. **学习目标**：完成教程后能够掌握的技能
-2. **前置条件**：需要的前置知识和环境
-3. **步骤 1-N**：分步说明（3-7 步）
-4. **完整代码**：汇总所有代码
-5. **运行结果**：预期输出和效果
-6. **下一步**：后续学习建议
-
-### 步骤格式
-
-每个步骤应包含：
-- 步骤标题（简短、动词开头）
-- 步骤说明（为什么要这样做）
-- 代码示例（完整且可运行）
-- 代码解释（关键部分的说明）
-
-**示例**：
-```markdown
-## 步骤 1：创建 Model 类
-
-首先，我们需要创建一个 Model 来存储玩家数据。Model 负责管理应用的数据和状态。
-
-\`\`\`csharp
-using GFramework.Core.Abstractions.model;
-using GFramework.Core.Abstractions.property;
-
-public class PlayerModel : IModel
-{
-    // 玩家名称（可绑定属性）
-    public BindableProperty<string> Name { get; } = new("Player");
-
-    // 玩家生命值
-    public BindableProperty<int> Health { get; } = new(100);
-
-    // 玩家金币
-    public BindableProperty<int> Gold { get; } = new(0);
-
-    public void Init() { }
-}
-\`\`\`
-
-**代码说明**：
-- `BindableProperty<T>` 是可绑定属性，值变化时会自动通知监听者
-- `Init()` 方法在 Model 注册到架构时被调用
-- 使用属性初始化器设置默认值
-```
-
-## 模板变量
-
-- `{{TUTORIAL_TITLE}}` - 教程标题
-- `{{TUTORIAL_DESCRIPTION}}` - 简短描述
-- `{{LEARNING_OBJECTIVES}}` - 学习目标
-- `{{PREREQUISITES}}` - 前置条件
-- `{{STEP_N_TITLE}}` - 步骤标题
-- `{{STEP_N_CONTENT}}` - 步骤内容
-- `{{FULL_CODE}}` - 完整代码
-- `{{EXPECTED_OUTPUT}}` - 预期输出
-- `{{NEXT_STEPS}}` - 下一步建议
-
-## 示例输出
-
-参考 `examples/tutorial-example.md`，该示例基于现有的教程文档创建。
-
-## 内容要求
-
-### 学习目标
-- 使用列表格式
-- 3-5 个具体的学习目标
-- 使用"能够..."句式
-
-**示例**：
-```markdown
-## 学习目标
-
-完成本教程后，你将能够：
-- 创建自定义的 Model 类
-- 在架构中注册 Model
-- 从 Controller 中访问 Model
-- 使用可绑定属性管理数据
-```
-
-### 前置条件
-- 列出必需的知识
-- 说明环境要求
-- 提供相关文档链接
-
-**示例**：
-```markdown
-## 前置条件
-
-- 已安装 GFramework.Core NuGet 包
-- 了解 C# 基础语法
-- 阅读过[架构概览](/zh-CN/getting-started)
-```
-
-### 步骤内容
-- 每步 100-300 字说明
-- 包含完整的代码示例
-- 解释关键代码的作用
-- 使用注释标注重要部分
-
-### 完整代码
-- 汇总所有步骤的代码
-- 确保可以直接复制运行
-- 包含必要的 using 语句
-- 添加文件结构说明
-
-### 运行结果
-- 描述预期的输出
-- 如果有界面，提供截图或描述
-- 说明如何验证结果正确
-
-### 下一步
-- 推荐 2-3 个后续教程
-- 提供相关文档链接
-- 建议进阶学习方向
-
-## 写作风格
-
-### 语气
-- 友好、鼓励性
-- 使用第二人称（"你"）
-- 避免假设读者已有高级知识
-
-### 步骤说明
-- 使用主动语态
-- 步骤标题使用动词开头
-- 说明"为什么"而不仅是"怎么做"
-
-### 代码示例
-- 完整且可运行
-- 包含详细注释
-- 使用有意义的变量名
-- 遵循项目代码风格
-
-## 配置选项
-
-### 教程难度
-
-```bash
-# 初学者（更多解释，简单示例）
-/vitepress-tutorial "创建第一个 System" --level beginner
-
-# 中级（平衡解释和复杂度）
-/vitepress-tutorial "实现自定义命令" --level intermediate
-
-# 高级（简洁说明，复杂示例）
-/vitepress-tutorial "架构模块开发" --level advanced
-```
-
-### 步骤数量
-
-```bash
-# 指定步骤数量（3-7 步）
-/vitepress-tutorial "使用事件系统" --steps 5
-```
-
-## 前置条件
-
-1. 了解教程主题的基本概念
-2. 能够访问相关代码文件
-3. 了解目标受众的知识水平
-
-## 相关 Skills
-
-- `/vitepress-api-doc` - 生成 API 参考文档
-- `/vitepress-guide` - 生成功能指南
-- `/vitepress-validate` - 验证生成的文档
-
-## 最佳实践
-
-1. **从简单开始**：第一步应该是最简单的操作
-2. **逐步增加复杂度**：每步在前一步基础上增加新内容
-3. **提供完整代码**：确保每步的代码都可以运行
-4. **解释关键概念**：不要假设读者已经了解所有术语
-5. **测试教程**：确保按照步骤操作能够得到预期结果
-
-## 故障排除
-
-### 问题：步骤过多，教程太长
-**解决方案**：将教程拆分为多个小教程，或合并相似的步骤
-
-### 问题：代码示例不完整
-**解决方案**：在"完整代码"章节提供所有文件的完整代码
-
-### 问题：读者反馈步骤不清晰
-**解决方案**：增加更多说明，使用截图或图表辅助
-
-## 版本历史
-
-- v1.0.0 - 初始版本，支持分步教程生成

.claude/skills/vitepress-tutorial/examples/tutorial-example.md

@@ -1,347 +0,0 @@
----
-title: 创建第一个 Model
-description: 学习如何创建和使用 Model 来管理应用数据
----
-
-# 创建第一个 Model
-
-## 学习目标
-
-完成本教程后，你将能够：
-- 理解 Model 在架构中的作用
-- 创建自定义的 Model 类
-- 在架构中注册 Model
-- 从 Controller 中访问 Model
-- 使用可绑定属性管理数据
-
-## 前置条件
-
-- 已安装 GFramework.Core NuGet 包
-- 了解 C# 基础语法
-- 阅读过[架构概览](/zh-CN/getting-started)
-
-## 步骤 1：创建 Model 类
-
-首先，我们需要创建一个 Model 来存储玩家数据。Model 负责管理应用的数据和状态。
-
-```csharp
-using GFramework.Core.Abstractions.model;
-using GFramework.Core.Abstractions.property;
-
-namespace MyGame.Models
-{
-    /// <summary>
-    /// 玩家数据模型
-    /// </summary>
-    public class PlayerModel : IModel
-    {
-        // 玩家名称（可绑定属性）
-        public BindableProperty<string> Name { get; } = new("Player");
-
-        // 玩家生命值
-        public BindableProperty<int> Health { get; } = new(100);
-
-        // 玩家金币
-        public BindableProperty<int> Gold { get; } = new(0);
-
-        // 玩家等级
-        public BindableProperty<int> Level { get; } = new(1);
-
-        /// <summary>
-        /// Model 初始化方法
-        /// </summary>
-        public void Init()
-        {
-            // 在这里可以进行初始化操作
-            // 例如：从配置文件加载默认值
-        }
-    }
-}
-```
-
-**代码说明**：
-- `IModel` 接口标识这是一个数据模型
-- `BindableProperty<T>` 是可绑定属性，值变化时会自动通知监听者
-- `Init()` 方法在 Model 注册到架构时被调用
-- 使用属性初始化器设置默认值
-
-## 步骤 2：在架构中注册 Model
-
-创建架构类并注册 Model：
-
-```csharp
-using GFramework.Core.architecture;
-using MyGame.Models;
-
-namespace MyGame
-{
-    /// <summary>
-    /// 游戏架构
-    /// </summary>
-    public class GameArchitecture : Architecture
-    {
-        // 单例访问点
-        public static IArchitecture Interface { get; private set; }
-
-        /// <summary>
-        /// 初始化架构
-        /// </summary>
-        protected override void Init()
-        {
-            Interface = this;
-
-            // 注册 Model
-            RegisterModel(new PlayerModel());
-        }
-    }
-}
-```
-
-**代码说明**：
-- 继承 `Architecture` 基类
-- 在 `Init()` 方法中注册 Model
-- 提供静态属性 `Interface` 用于全局访问架构
-
-## 步骤 3：创建 Controller 访问 Model
-
-创建 Controller 来使用 Model：
-
-```csharp
-using GFramework.Core.Abstractions.architecture;
-using GFramework.Core.Abstractions.controller;
-using GFramework.Core.extensions;
-using MyGame.Models;
-
-namespace MyGame.Controllers
-{
-    /// <summary>
-    /// 游戏控制器
-    /// </summary>
-    public class GameController : IController
-    {
-        /// <summary>
-        /// 获取架构实例
-        /// </summary>
-        public IArchitecture GetArchitecture() => GameArchitecture.Interface;
-
-        /// <summary>
-        /// 初始化玩家数据
-        /// </summary>
-        public void InitializePlayer()
-        {
-            // 获取 PlayerModel
-            var playerModel = this.GetModel<PlayerModel>();
-
-            // 设置玩家数据
-            playerModel.Name.Value = "勇者";
-            playerModel.Health.Value = 100;
-            playerModel.Gold.Value = 50;
-            playerModel.Level.Value = 1;
-
-            // 监听属性变化
-            playerModel.Health.RegisterOnValueChanged(health =>
-            {
-                Console.WriteLine($"玩家生命值变化: {health}");
-
-                if (health <= 0)
-                {
-                    Console.WriteLine("玩家死亡！");
-                }
-            });
-        }
-
-        /// <summary>
-        /// 玩家受到伤害
-        /// </summary>
-        public void TakeDamage(int damage)
-        {
-            var playerModel = this.GetModel<PlayerModel>();
-            playerModel.Health.Value -= damage;
-        }
-
-        /// <summary>
-        /// 玩家获得金币
-        /// </summary>
-        public void AddGold(int amount)
-        {
-            var playerModel = this.GetModel<PlayerModel>();
-            playerModel.Gold.Value += amount;
-        }
-    }
-}
-```
-
-**代码说明**：
-- 实现 `IController` 接口
-- 通过 `this.GetModel<T>()` 扩展方法获取 Model
-- 使用 `.Value` 访问和修改属性值
-- 使用 `RegisterOnValueChanged` 监听属性变化
-
-## 步骤 4：初始化并使用架构
-
-在程序入口点初始化架构：
-
-```csharp
-using MyGame;
-using MyGame.Controllers;
-
-// 1. 创建并初始化架构
-var architecture = new GameArchitecture();
-architecture.Initialize();
-
-// 2. 等待架构就绪
-await architecture.WaitUntilReadyAsync();
-
-// 3. 创建 Controller 并使用
-var gameController = new GameController();
-
-// 初始化玩家
-gameController.InitializePlayer();
-
-// 玩家受到伤害
-gameController.TakeDamage(20);
-// 输出: 玩家生命值变化: 80
-
-// 玩家获得金币
-gameController.AddGold(100);
-```
-
-**代码说明**：
-- 创建架构实例并调用 `Initialize()`
-- 使用 `WaitUntilReadyAsync()` 等待架构就绪
-- 创建 Controller 实例并调用方法
-
-## 完整代码
-
-### PlayerModel.cs
-
-```csharp
-using GFramework.Core.Abstractions.model;
-using GFramework.Core.Abstractions.property;
-
-namespace MyGame.Models
-{
-    public class PlayerModel : IModel
-    {
-        public BindableProperty<string> Name { get; } = new("Player");
-        public BindableProperty<int> Health { get; } = new(100);
-        public BindableProperty<int> Gold { get; } = new(0);
-        public BindableProperty<int> Level { get; } = new(1);
-
-        public void Init() { }
-    }
-}
-```
-
-### GameArchitecture.cs
-
-```csharp
-using GFramework.Core.architecture;
-using MyGame.Models;
-
-namespace MyGame
-{
-    public class GameArchitecture : Architecture
-    {
-        public static IArchitecture Interface { get; private set; }
-
-        protected override void Init()
-        {
-            Interface = this;
-            RegisterModel(new PlayerModel());
-        }
-    }
-}
-```
-
-### GameController.cs
-
-```csharp
-using GFramework.Core.Abstractions.architecture;
-using GFramework.Core.Abstractions.controller;
-using GFramework.Core.extensions;
-using MyGame.Models;
-
-namespace MyGame.Controllers
-{
-    public class GameController : IController
-    {
-        public IArchitecture GetArchitecture() => GameArchitecture.Interface;
-
-        public void InitializePlayer()
-        {
-            var playerModel = this.GetModel<PlayerModel>();
-            playerModel.Name.Value = "勇者";
-            playerModel.Health.Value = 100;
-            playerModel.Gold.Value = 50;
-            playerModel.Level.Value = 1;
-
-            playerModel.Health.RegisterOnValueChanged(health =>
-            {
-                Console.WriteLine($"玩家生命值变化: {health}");
-                if (health <= 0)
-                {
-                    Console.WriteLine("玩家死亡！");
-                }
-            });
-        }
-
-        public void TakeDamage(int damage)
-        {
-            var playerModel = this.GetModel<PlayerModel>();
-            playerModel.Health.Value -= damage;
-        }
-
-        public void AddGold(int amount)
-        {
-            var playerModel = this.GetModel<PlayerModel>();
-            playerModel.Gold.Value += amount;
-        }
-    }
-}
-```
-
-### Program.cs
-
-```csharp
-using MyGame;
-using MyGame.Controllers;
-
-var architecture = new GameArchitecture();
-architecture.Initialize();
-await architecture.WaitUntilReadyAsync();
-
-var gameController = new GameController();
-gameController.InitializePlayer();
-gameController.TakeDamage(20);
-gameController.AddGold(100);
-```
-
-## 运行结果
-
-运行程序后，你将看到以下输出：
-
-```
-玩家生命值变化: 100
-玩家生命值变化: 80
-```
-
-**验证步骤**：
-1. 程序成功启动，没有异常
-2. 控制台输出生命值变化信息
-3. 玩家数据正确更新
-
-## 下一步
-
-恭喜！你已经学会了如何创建和使用 Model。接下来可以学习：
-
-- [创建第一个 System](/zh-CN/tutorials/create-first-system) - 学习如何创建业务逻辑层
-- [使用命令系统](/zh-CN/tutorials/use-command-system) - 学习如何封装操作
-- [使用事件系统](/zh-CN/tutorials/use-event-system) - 学习组件间通信
-
-## 相关文档
-
-- [Model 层](/zh-CN/core/model) - Model 详细说明
-- [属性系统](/zh-CN/core/property) - 可绑定属性详解
-- [架构组件](/zh-CN/core/architecture) - 架构基础
-- [Controller 层](/zh-CN/core/controller) - Controller 详细说明

.claude/skills/vitepress-tutorial/template.md

@@ -1,42 +0,0 @@
----
-title: {{TUTORIAL_TITLE}}
-description: {{TUTORIAL_DESCRIPTION}}
----
-
-# {{TUTORIAL_TITLE}}
-
-## 学习目标
-
-{{LEARNING_OBJECTIVES}}
-
-## 前置条件
-
-{{PREREQUISITES}}
-
-## 步骤 1：{{STEP_1_TITLE}}
-
-{{STEP_1_CONTENT}}
-
-## 步骤 2：{{STEP_2_TITLE}}
-
-{{STEP_2_CONTENT}}
-
-## 步骤 3：{{STEP_3_TITLE}}
-
-{{STEP_3_CONTENT}}
-
-## 完整代码
-
-{{FULL_CODE}}
-
-## 运行结果
-
-{{EXPECTED_OUTPUT}}
-
-## 下一步
-
-{{NEXT_STEPS}}
-
-## 相关文档
-
-{{RELATED_DOCS}}

.claude/skills/vitepress-validate/SKILL.md

@@ -1,297 +0,0 @@
-# VitePress 文档验证
-
-验证 VitePress 文档的质量和规范性，确保文档符合项目标准。
-
-## 用途
-
-此 skill 用于验证 Markdown 文档的格式和内容，包括：
-- Frontmatter 格式正确性
-- 内部链接有效性
-- 代码块语法标记
-- 标题层级结构
-- 中文标点符号规范
-- 泛型符号转义
-
-## 调用方式
-
-```bash
-# 验证单个文件
-/vitepress-validate <文件路径>
-
-# 验证整个目录
-/vitepress-validate <目录路径>
-
-# 验证所有文档
-/vitepress-validate docs/zh-CN/
-```
-
-**示例**：
-```bash
-/vitepress-validate docs/zh-CN/api-reference/core/architecture.md
-/vitepress-validate docs/zh-CN/core/
-```
-
-## 验证项
-
-### 1. Frontmatter 验证
-
-**检查项**：
-- YAML 语法正确性
-- 必需字段存在（`title`、`description`）
-- 字段值类型正确
-- `outline` 字段值有效（`deep`、`[2,3]` 等）
-
-**示例**：
-```yaml
----
-title: Architecture  # 必需
-description: 架构基类说明  # 必需
-outline: deep  # 可选，但值必须有效
----
-```
-
-### 2. 内部链接验证
-
-**检查项**：
-- 相对路径链接指向的文件存在
-- 绝对路径链接格式正确
-- 锚点链接对应的标题存在
-- 没有损坏的链接
-
-**有效链接格式**：
-- `[文本](./file.md)` - 相对路径
-- `[文本](/zh-CN/core/architecture)` - 绝对路径
-- `[文本](#标题)` - 锚点链接
-- `[文本](./file.md#标题)` - 组合链接
-
-### 3. 代码块验证
-
-**检查项**：
-- 代码块有语法标记（```csharp、```bash 等）
-- C# 代码块使用 `csharp` 标记（不是 `cs` 或 `c#`）
-- 代码块正确闭合
-- 没有未闭合的反引号
-
-**正确格式**：
-```markdown
-\`\`\`csharp
-public class Example { }
-\`\`\`
-```
-
-**错误格式**：
-```markdown
-\`\`\`cs  // 应该使用 csharp
-public class Example { }
-\`\`\`
-```
-
-### 4. 标题层级验证
-
-**检查项**：
-- 标题层级不跳级（不能从 `#` 直接跳到 `###`）
-- 每个文档只有一个一级标题（`#`）
-- 标题层级递增合理
-
-**正确示例**：
-```markdown
-# 一级标题
-## 二级标题
-### 三级标题
-## 另一个二级标题
-```
-
-**错误示例**：
-```markdown
-# 一级标题
-### 三级标题  ❌ 跳过了二级标题
-```
-
-### 5. 中文标点符号验证
-
-**检查项**：
-- 中文句子使用全角标点（，。！？）
-- 英文句子使用半角标点（,.!?）
-- 代码和技术术语周围使用半角符号
-- 括号使用规范
-
-**规范示例**：
-- "这是一个示例。" ✓（中文全角句号）
-- "This is an example." ✓（英文半角句号）
-- "`Architecture` 类提供了..." ✓（代码周围半角）
-
-### 6. 泛型符号验证
-
-**检查项**：
-- 泛型符号正确转义（`<T>` → `&lt;T&gt;`）
-- 仅在代码块外转义
-- 代码块内保持原样
-
-**正确示例**：
-```markdown
-`List&lt;T&gt;` 是一个泛型类。
-
-\`\`\`csharp
-List<T> items = new List<T>();  // 代码块内不转义
-\`\`\`
-```
-
-## 验证脚本
-
-### validate-frontmatter.sh
-
-验证 Frontmatter 格式。
-
-**用法**：
-```bash
-.claude/skills/vitepress-validate/scripts/validate-frontmatter.sh <文件路径>
-```
-
-### validate-links.sh
-
-验证内部链接有效性。
-
-**用法**：
-```bash
-.claude/skills/vitepress-validate/scripts/validate-links.sh <文件路径>
-```
-
-### validate-code-blocks.sh
-
-验证代码块语法。
-
-**用法**：
-```bash
-.claude/skills/vitepress-validate/scripts/validate-code-blocks.sh <文件路径>
-```
-
-### validate-all.sh
-
-执行所有验证。
-
-**用法**：
-```bash
-.claude/skills/vitepress-validate/scripts/validate-all.sh <文件或目录路径>
-```
-
-## 输出格式
-
-### 验证通过
-
-```
-✓ docs/zh-CN/core/architecture.md
-  - Frontmatter: 通过
-  - 内部链接: 通过
-  - 代码块: 通过
-  - 标题层级: 通过
-  - 标点符号: 通过
-  - 泛型符号: 通过
-```
-
-### 验证失败
-
-```
-✗ docs/zh-CN/core/architecture.md
-  - Frontmatter: 失败
-    × 缺少必需字段: description
-  - 内部链接: 失败
-    × 损坏的链接: ./missing-file.md (第 45 行)
-  - 代码块: 警告
-    ⚠ 使用了 'cs' 标记，建议使用 'csharp' (第 78 行)
-  - 标题层级: 通过
-  - 标点符号: 警告
-    ⚠ 中文句子使用了半角句号 (第 102 行)
-  - 泛型符号: 失败
-    × 未转义的泛型符号: List<T> (第 120 行)
-```
-
-## 修复建议
-
-验证失败时，skill 会提供具体的修复建议：
-
-**示例**：
-```
-修复建议:
-1. 在 Frontmatter 中添加 description 字段
-2. 修复或删除损坏的链接: ./missing-file.md
-3. 将代码块标记从 'cs' 改为 'csharp'
-4. 将第 102 行的半角句号改为全角句号
-5. 将第 120 行的 List<T> 改为 List&lt;T&gt;
-```
-
-## 配置选项
-
-### 严格模式
-
-启用严格模式时，警告也会导致验证失败。
-
-```bash
-/vitepress-validate --strict docs/zh-CN/
-```
-
-### 忽略特定检查
-
-```bash
-# 忽略标点符号检查
-/vitepress-validate --ignore-punctuation docs/zh-CN/
-
-# 忽略多个检查
-/vitepress-validate --ignore-punctuation --ignore-generics docs/zh-CN/
-```
-
-## 集成到工作流
-
-### 生成后自动验证
-
-```bash
-# 1. 生成 API 文档
-/vitepress-api-doc GFramework.Core/architecture/Architecture.cs
-
-# 2. 自动验证生成的文档
-/vitepress-validate docs/zh-CN/api-reference/core/architecture.md
-```
-
-### 批量验证
-
-```bash
-# 验证所有 API 文档
-/vitepress-validate docs/zh-CN/api-reference/
-
-# 验证所有文档
-/vitepress-validate docs/zh-CN/
-```
-
-## 退出代码
-
-- `0` - 所有验证通过
-- `1` - 存在错误
-- `2` - 仅存在警告（非严格模式下仍返回 0）
-
-## 相关 Skills
-
-- `/vitepress-api-doc` - 生成 API 文档后自动验证
-- `/vitepress-guide` - 生成指南文档后自动验证
-- `/vitepress-tutorial` - 生成教程文档后自动验证
-
-## 最佳实践
-
-1. **生成后立即验证**：每次生成文档后立即运行验证
-2. **定期批量验证**：定期验证所有文档，确保一致性
-3. **修复所有错误**：不要忽略验证错误，及时修复
-4. **关注警告**：警告虽不致命，但应该重视并修复
-5. **使用严格模式**：在 CI/CD 中使用严格模式确保质量
-
-## 故障排除
-
-### 问题：误报泛型符号错误
-**解决方案**：确保泛型符号在代码块外正确转义，代码块内保持原样
-
-### 问题：中文标点符号检查过于严格
-**解决方案**：使用 `--ignore-punctuation` 选项，或手动调整规则
-
-### 问题：链接验证失败但文件确实存在
-**解决方案**：检查文件路径大小写，确保路径完全匹配
-
-## 版本历史
-
-- v1.0.0 - 初始版本，支持 6 项基本验证

.claude/skills/vitepress-validate/scripts/validate-all.sh

@@ -1,109 +0,0 @@
-#!/bin/bash
-# 执行所有验证
-# 用法: validate-all.sh <文件或目录路径>
-
-set -e
-
-TARGET="$1"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-if [ -z "$TARGET" ]; then
-    echo "用法: $0 <文件或目录路径>"
-    exit 1
-fi
-
-if [ ! -e "$TARGET" ]; then
-    echo "错误: 路径不存在: $TARGET"
-    exit 1
-fi
-
-echo "=========================================="
-echo "VitePress 文档验证"
-echo "=========================================="
-echo ""
-
-# 收集所有 Markdown 文件
-if [ -f "$TARGET" ]; then
-    FILES=("$TARGET")
-elif [ -d "$TARGET" ]; then
-    mapfile -t FILES < <(find "$TARGET" -name "*.md" -type f)
-else
-    echo "错误: 无效的路径: $TARGET"
-    exit 1
-fi
-
-if [ ${#FILES[@]} -eq 0 ]; then
-    echo "未找到 Markdown 文件"
-    exit 0
-fi
-
-echo "找到 ${#FILES[@]} 个文件"
-echo ""
-
-TOTAL_ERRORS=0
-TOTAL_WARNINGS=0
-PASSED_FILES=0
-FAILED_FILES=0
-
-for FILE in "${FILES[@]}"; do
-    echo "验证: $FILE"
-    echo "----------------------------------------"
-
-    FILE_ERRORS=0
-    FILE_WARNINGS=0
-
-    # 1. Frontmatter 验证
-    if bash "$SCRIPT_DIR/validate-frontmatter.sh" "$FILE" 2>&1 | grep -q "✗"; then
-        FILE_ERRORS=$((FILE_ERRORS + 1))
-    fi
-
-    # 2. 链接验证
-    if bash "$SCRIPT_DIR/validate-links.sh" "$FILE" 2>&1 | grep -q "✗"; then
-        FILE_ERRORS=$((FILE_ERRORS + 1))
-    fi
-
-    # 3. 代码块验证
-    OUTPUT=$(bash "$SCRIPT_DIR/validate-code-blocks.sh" "$FILE" 2>&1 || true)
-    if echo "$OUTPUT" | grep -q "✗"; then
-        FILE_ERRORS=$((FILE_ERRORS + 1))
-    fi
-    if echo "$OUTPUT" | grep -q "⚠"; then
-        FILE_WARNINGS=$((FILE_WARNINGS + 1))
-    fi
-
-    # 统计结果
-    if [ $FILE_ERRORS -eq 0 ]; then
-        echo "✓ 验证通过"
-        PASSED_FILES=$((PASSED_FILES + 1))
-    else
-        echo "✗ 验证失败（$FILE_ERRORS 个错误）"
-        FAILED_FILES=$((FAILED_FILES + 1))
-    fi
-
-    if [ $FILE_WARNINGS -gt 0 ]; then
-        echo "⚠ $FILE_WARNINGS 个警告"
-    fi
-
-    TOTAL_ERRORS=$((TOTAL_ERRORS + FILE_ERRORS))
-    TOTAL_WARNINGS=$((TOTAL_WARNINGS + FILE_WARNINGS))
-
-    echo ""
-done
-
-echo "=========================================="
-echo "验证摘要"
-echo "=========================================="
-echo "总文件数: ${#FILES[@]}"
-echo "通过: $PASSED_FILES"
-echo "失败: $FAILED_FILES"
-echo "总错误数: $TOTAL_ERRORS"
-echo "总警告数: $TOTAL_WARNINGS"
-echo ""
-
-if [ $TOTAL_ERRORS -eq 0 ]; then
-    echo "✓ 所有验证通过"
-    exit 0
-else
-    echo "✗ 验证失败"
-    exit 1
-fi

.claude/skills/vitepress-validate/scripts/validate-code-blocks.sh

@@ -1,64 +0,0 @@
-#!/bin/bash
-# 验证代码块语法
-# 用法: validate-code-blocks.sh <文件路径>
-
-set -e
-
-FILE="$1"
-
-if [ -z "$FILE" ]; then
-    echo "用法: $0 <文件路径>"
-    exit 1
-fi
-
-if [ ! -f "$FILE" ]; then
-    echo "错误: 文件不存在: $FILE"
-    exit 1
-fi
-
-echo "验证代码块语法: $FILE"
-
-ERROR_COUNT=0
-WARNING_COUNT=0
-
-# 检查未闭合的代码块
-OPEN_COUNT=$(grep -c '^```' "$FILE" || true)
-if [ $((OPEN_COUNT % 2)) -ne 0 ]; then
-    echo "✗ 错误: 存在未闭合的代码块"
-    ERROR_COUNT=$((ERROR_COUNT + 1))
-fi
-
-# 检查 C# 代码块标记
-LINE_NUM=0
-while IFS= read -r LINE; do
-    LINE_NUM=$((LINE_NUM + 1))
-
-    # 检查是否使用了错误的 C# 标记
-    if echo "$LINE" | grep -qE '^```(cs|c#|C#)$'; then
-        echo "⚠ 警告: 第 $LINE_NUM 行使用了非标准标记，建议使用 'csharp'"
-        echo "  当前: $LINE"
-        WARNING_COUNT=$((WARNING_COUNT + 1))
-    fi
-
-    # 检查代码块是否有语言标记
-    if echo "$LINE" | grep -qE '^```$'; then
-        # 检查下一行是否是代码（简单启发式：不是空行且不是 ```）
-        NEXT_LINE=$(sed -n "$((LINE_NUM + 1))p" "$FILE")
-        if [ -n "$NEXT_LINE" ] && ! echo "$NEXT_LINE" | grep -qE '^```'; then
-            echo "⚠ 警告: 第 $LINE_NUM 行的代码块缺少语言标记"
-            WARNING_COUNT=$((WARNING_COUNT + 1))
-        fi
-    fi
-done < "$FILE"
-
-# 输出结果
-if [ $ERROR_COUNT -eq 0 ] && [ $WARNING_COUNT -eq 0 ]; then
-    echo "✓ 代码块验证通过"
-    exit 0
-elif [ $ERROR_COUNT -eq 0 ]; then
-    echo "⚠ 代码块验证通过（有 $WARNING_COUNT 个警告）"
-    exit 0
-else
-    echo "✗ 代码块验证失败（$ERROR_COUNT 个错误，$WARNING_COUNT 个警告）"
-    exit 1
-fi

.claude/skills/vitepress-validate/scripts/validate-frontmatter.sh

@@ -1,57 +0,0 @@
-#!/bin/bash
-# 验证 Frontmatter 格式
-# 用法: validate-frontmatter.sh <文件路径>
-
-set -e
-
-FILE="$1"
-
-if [ -z "$FILE" ]; then
-    echo "用法: $0 <文件路径>"
-    exit 1
-fi
-
-if [ ! -f "$FILE" ]; then
-    echo "错误: 文件不存在: $FILE"
-    exit 1
-fi
-
-echo "验证 Frontmatter: $FILE"
-
-# 检查是否有 Frontmatter（限制在前几行，避免匹配正文中的 '---'）
-if ! head -n 5 "$FILE" | grep -q "^---$"; then
-    echo "✗ 错误: 文件缺少 Frontmatter"
-    exit 1
-fi
-
-# 提取 Frontmatter 内容（第一个 --- 到第二个 --- 之间）
-FRONTMATTER=$(sed -n '/^---$/,/^---$/p' "$FILE" | sed '1d;$d')
-
-if [ -z "$FRONTMATTER" ]; then
-    echo "✗ 错误: Frontmatter 为空"
-    exit 1
-fi
-
-# 检查必需字段: title
-if ! echo "$FRONTMATTER" | grep -q "^title:"; then
-    echo "✗ 错误: 缺少必需字段: title"
-    exit 1
-fi
-
-# 检查必需字段: description
-if ! echo "$FRONTMATTER" | grep -q "^description:"; then
-    echo "✗ 错误: 缺少必需字段: description"
-    exit 1
-fi
-
-# 检查 outline 字段值（如果存在）
-if echo "$FRONTMATTER" | grep -q "^outline:"; then
-    OUTLINE_VALUE=$(echo "$FRONTMATTER" | grep "^outline:" | sed 's/outline:\s*//')
-    if [ "$OUTLINE_VALUE" != "deep" ] && [ "$OUTLINE_VALUE" != "false" ] && ! echo "$OUTLINE_VALUE" | grep -qE '^\[.*\]$'; then
-        echo "⚠ 警告: outline 字段值可能无效: $OUTLINE_VALUE"
-        echo "  有效值: deep, false, [2,3]"
-    fi
-fi
-
-echo "✓ Frontmatter 验证通过"
-exit 0

.coderabbit.yaml

@@ -0,0 +1,26 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: "zh-CN"
+early_access: false
+
+reviews:
+  profile: "chill"
+  request_changes_workflow: true # 有问题时可以直接 request changes
+  high_level_summary: true # PR 总体总结
+  review_status: true # review 结果状态
+  review_details: true # 展示具体问题
+  poem: false # 关闭诗歌（基本没人用）
+  tools:
+    github-checks:
+      enabled: true
+      timeout_ms: 900000
+  auto_review:
+    enabled: true
+    drafts: false # draft PR 不 review
+    base_branches:
+      - refactor/cqrs-architecture-decoupling
+
+chat:
+  auto_reply: true

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+
+[*.sln]
+end_of_line = crlf
+
+[*.bat]
+end_of_line = crlf
+
+[*.cmd]
+end_of_line = crlf
+
+[*.ps1]
+end_of_line = crlf

.feluda.yaml

@@ -1,4 +1,7 @@
-license_overrides:
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+license_overrides:
   NETStandard.Library: MIT
   Microsoft.NETCore.Platforms: MIT
   System.Buffers: MIT

.gitattributes

@@ -0,0 +1,35 @@
+# Keep repository text normalized to LF unless a file format is known to require CRLF.
+* text=auto eol=lf
+
+# Solution and Windows-native scripts are more interoperable when they keep CRLF in the working tree.
+*.sln text eol=crlf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# Source, config, scripts, and documentation stay LF across WSL and Windows editors.
+*.sh text eol=lf
+*.cs text eol=lf
+*.csproj text eol=lf
+*.props text eol=lf
+*.targets text eol=lf
+*.json text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.md text eol=lf
+*.ts text eol=lf
+*.js text eol=lf
+*.mts text eol=lf
+*.vue text eol=lf
+*.css text eol=lf
+
+# Common binary assets should never be line-normalized.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.zip binary
+*.dll binary
+*.so binary
+*.pdb binary

.github/ISSUE_TEMPLATE/01-bug-report.yml

@@ -0,0 +1,125 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+name: "Bug Report / 缺陷报告"
+description: "Report a reproducible defect in GFramework. / 报告可稳定复现的 GFramework 缺陷。"
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug.
+
+        感谢你提交缺陷报告。提交前请先搜索已有 Issue，并尽量提供最小复现信息。
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: "Pre-Submission Checks / 提交前检查"
+      description: "Please confirm the following items before submitting. / 提交前请确认以下事项。"
+      options:
+        - label: "I searched existing issues and did not find a duplicate. / 我已搜索现有 Issue，未发现重复问题。"
+          required: true
+        - label: "I checked the relevant README or docs pages first. / 我已先阅读相关 README 或文档。"
+          required: true
+        - label: "I can describe a reproducible scenario or provide a minimal repro. / 我可以描述稳定复现场景或提供最小复现。"
+          required: true
+  - type: dropdown
+    id: module
+    attributes:
+      label: "Affected Module / 影响模块"
+      description: "Choose the module that best matches the problem. / 请选择最符合问题范围的模块。"
+      options:
+        - "GFramework.Core"
+        - "GFramework.Core.Abstractions"
+        - "GFramework.Game"
+        - "GFramework.Game.Abstractions"
+        - "GFramework.Godot"
+        - "GFramework.SourceGenerators"
+        - "GFramework.Godot.SourceGenerators"
+        - "Docs / 文档"
+        - "Build / CI / Packaging"
+        - "Unknown / Not sure / 不确定"
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: "Package or Commit Version / 包版本或提交版本"
+      description: "Example: NuGet version, commit SHA, or branch. / 例如 NuGet 版本、提交 SHA 或分支。"
+      placeholder: "e.g. GeWuYou.GFramework.Core 1.2.3 / main@abc1234"
+    validations:
+      required: true
+  - type: textarea
+    id: summary
+    attributes:
+      label: "Bug Summary / 问题概述"
+      description: "Describe the defect in one or two paragraphs. / 用 1-2 段简要描述问题。"
+      placeholder: "What is broken, and when does it happen? / 具体哪里出错，什么情况下出现？"
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: "Steps To Reproduce / 复现步骤"
+      description: "Provide a deterministic repro whenever possible. / 尽量提供可稳定复现的步骤。"
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: "Expected Behavior / 预期行为"
+      description: "What should happen instead? / 正常情况下应该发生什么？"
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: "Actual Behavior / 实际行为"
+      description: "What actually happens? Include exception text if available. / 实际发生了什么？如有异常请附上。"
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: "Minimal Repro / 最小复现"
+      description: "Share a repository, gist, code snippet, or explain why a minimal repro is not yet available. / 提供仓库、gist、代码片段，或说明暂时无法提供的原因。"
+      placeholder: |
+        Please provide one of the following:
+        - A GitHub repository or sample project
+        - A gist or focused code snippet
+        - Or explain why a minimal repro is not yet available
+
+        请提供以下任一内容：
+        - GitHub 仓库或示例项目
+        - Gist 或聚焦代码片段
+        - 或说明暂时无法提供最小复现的原因
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: "Logs and Screenshots / 日志与截图"
+      description: "Paste relevant logs, stack traces, or attach screenshots. / 粘贴相关日志、堆栈，或补充截图。"
+      render: shell
+  - type: textarea
+    id: environment
+    attributes:
+      label: "Environment / 环境信息"
+      description: "List the environment details that matter for reproduction. / 请列出与复现相关的环境信息。"
+      placeholder: |
+        - OS:
+        - .NET SDK / Runtime:
+        - Godot version (if applicable):
+        - IDE / Build tool:
+    validations:
+      required: true
+  - type: textarea
+    id: impact
+    attributes:
+      label: "Impact and Scope / 影响范围"
+      description: "Explain whether this blocks adoption, breaks compatibility, or affects only a narrow scenario. / 说明该问题是否阻塞使用、破坏兼容性，还是仅影响较窄场景。"

.github/ISSUE_TEMPLATE/02-feature-request.yml

@@ -0,0 +1,83 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+name: "Feature Request / 功能建议"
+description: "Suggest a new capability or an API improvement. / 提出新能力或 API 改进建议。"
+title: "[Feature]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for feature proposals, API improvements, and workflow enhancements.
+
+        该模板适用于新功能、API 改进和工作流优化建议。请优先描述问题和动机，而不只是直接给出实现方案。
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: "Pre-Submission Checks / 提交前检查"
+      description: "Please confirm the following items before submitting. / 提交前请确认以下事项。"
+      options:
+        - label: "I searched existing issues and did not find the same request. / 我已搜索现有 Issue，未发现相同建议。"
+          required: true
+        - label: "I checked the relevant docs, examples, or current APIs first. / 我已先检查相关文档、示例或现有 API。"
+          required: true
+        - label: "I can explain the user problem or workflow gap this request solves. / 我可以说明该建议要解决的用户问题或工作流缺口。"
+          required: true
+  - type: dropdown
+    id: module
+    attributes:
+      label: "Target Module / 目标模块"
+      description: "Choose the module that should own this capability. / 请选择最适合承载该能力的模块。"
+      options:
+        - "GFramework.Core"
+        - "GFramework.Core.Abstractions"
+        - "GFramework.Game"
+        - "GFramework.Game.Abstractions"
+        - "GFramework.Godot"
+        - "GFramework.SourceGenerators"
+        - "GFramework.Godot.SourceGenerators"
+        - "Docs / 文档"
+        - "Build / CI / Packaging"
+        - "Cross-cutting / 跨模块"
+        - "Unknown / Not sure / 不确定"
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: "Problem Statement / 问题背景"
+      description: "What problem are you facing today? / 你当前遇到的核心问题是什么？"
+      placeholder: "Describe the workflow pain, limitation, or missing capability. / 描述当前流程痛点、限制或缺失能力。"
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: "Proposed Solution / 建议方案"
+      description: "Describe the behavior, API shape, or user experience you want. / 描述你期望的行为、API 形态或使用体验。"
+      placeholder: "What should GFramework provide? / 希望 GFramework 提供什么？"
+    validations:
+      required: true
+  - type: textarea
+    id: use-cases
+    attributes:
+      label: "Use Cases / 使用场景"
+      description: "Show the practical scenarios this would unlock or simplify. / 说明该能力能解决或简化哪些实际场景。"
+    validations:
+      required: true
+  - type: textarea
+    id: api-sketch
+    attributes:
+      label: "API or Design Sketch / API 或设计草图"
+      description: "Optional but helpful: provide pseudocode, API examples, or a rough design. / 可选但强烈建议：补充伪代码、API 示例或设计草图。"
+      render: csharp
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: "Alternatives Considered / 已考虑的替代方案"
+      description: "Describe current workarounds or alternatives and why they are insufficient. / 描述现有替代方案或绕过方式，以及为什么不足。"
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: "Compatibility and Migration Impact / 兼容性与迁移影响"
+      description: "State whether this needs breaking changes, opt-in behavior, or migration notes. / 说明该建议是否涉及破坏性变更、显式开关或迁移说明。"

.github/ISSUE_TEMPLATE/03-documentation.yml

@@ -0,0 +1,64 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+name: "Documentation / 文档改进"
+description: "Report missing, outdated, or unclear documentation. / 报告缺失、过期或不清晰的文档。"
+title: "[Docs]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Documentation issues are product issues in this repository.
+
+        文档问题同样是产品问题。请尽量指出具体页面、段落和建议修正方向，方便快速处理。
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: "Pre-Submission Checks / 提交前检查"
+      description: "Please confirm the following items before submitting. / 提交前请确认以下事项。"
+      options:
+        - label: "I searched existing issues and did not find the same documentation problem. / 我已搜索现有 Issue，未发现相同文档问题。"
+          required: true
+        - label: "I checked the latest docs site or repository docs pages first. / 我已先检查最新文档站点或仓库文档页面。"
+          required: true
+  - type: input
+    id: page
+    attributes:
+      label: "Document Path or URL / 文档路径或链接"
+      description: "Provide the file path or docs URL if you know it. / 如果知道，请提供文档文件路径或页面链接。"
+      placeholder: "e.g. docs/zh-CN/core/architecture.md"
+    validations:
+      required: true
+  - type: dropdown
+    id: doc-issue-type
+    attributes:
+      label: "Issue Type / 问题类型"
+      description: "Choose the primary documentation problem. / 请选择主要问题类型。"
+      options:
+        - "Missing content / 缺少内容"
+        - "Outdated content / 内容过期"
+        - "Incorrect content / 内容错误"
+        - "Unclear explanation / 说明不清晰"
+        - "Missing example / 缺少示例"
+        - "Translation issue / 翻译问题"
+    validations:
+      required: true
+  - type: textarea
+    id: current-problem
+    attributes:
+      label: "Current Problem / 当前问题"
+      description: "Describe what is confusing, wrong, or missing. / 说明当前哪里令人困惑、错误或缺失。"
+    validations:
+      required: true
+  - type: textarea
+    id: expected-docs
+    attributes:
+      label: "Expected Improvement / 期望改进"
+      description: "Describe the improvement you expect. / 说明你期望如何改进。"
+    validations:
+      required: true
+  - type: textarea
+    id: references
+    attributes:
+      label: "Related Code or References / 相关代码或参考资料"
+      description: "Link related source files, PRs, issues, or external references if helpful. / 如有帮助，请附上相关源码、PR、Issue 或外部参考资料。"

.github/ISSUE_TEMPLATE/04-question.yml

@@ -0,0 +1,69 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+name: "Question / 使用咨询"
+description: "Ask for guidance about usage, behavior, or adoption. / 询问用法、行为或接入方式。"
+title: "[Question]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form when your question is specific to GFramework behavior, APIs, or adoption guidance.
+
+        如果你的问题与 GFramework 的行为、API 或接入方式直接相关，请使用此模板。一般咨询请先查看 README、贡献指南与 docs。
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: "Pre-Submission Checks / 提交前检查"
+      description: "Please confirm the following items before submitting. / 提交前请确认以下事项。"
+      options:
+        - label: "I searched existing issues and read the relevant docs first. / 我已先搜索现有 Issue 并阅读相关文档。"
+          required: true
+        - label: "This is not a private support request or unrelated general programming question. / 这不是私有支持请求，也不是与本项目无关的泛编程问题。"
+          required: true
+  - type: dropdown
+    id: topic
+    attributes:
+      label: "Topic Area / 主题领域"
+      description: "Choose the area closest to your question. / 请选择最接近问题的主题。"
+      options:
+        - "Architecture / 架构"
+        - "Core APIs / Core API"
+        - "Game Module / Game 模块"
+        - "Godot Integration / Godot 集成"
+        - "Source Generators / 源生成器"
+        - "Build / Packaging / 构建与打包"
+        - "Docs / 文档"
+        - "Other / 其他"
+    validations:
+      required: true
+  - type: textarea
+    id: goal
+    attributes:
+      label: "What Are You Trying To Do? / 你想实现什么？"
+      description: "Explain your goal before describing the problem. / 请先说明你的目标，再描述遇到的问题。"
+      placeholder: "I want to... / 我想要……"
+    validations:
+      required: true
+  - type: textarea
+    id: current-attempt
+    attributes:
+      label: "Current Attempt / 当前尝试"
+      description: "Show what you already tried, including code, docs, or configuration. / 说明你已经尝试过什么，包括代码、文档或配置。"
+      render: csharp
+    validations:
+      required: true
+  - type: textarea
+    id: question
+    attributes:
+      label: "Specific Question / 具体问题"
+      description: "Ask the narrowest question that would unblock you. / 提出能真正帮你解阻的最小问题。"
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: "Relevant Environment / 相关环境"
+      description: "Include the framework version, runtime, engine version, or project context. If not applicable, write N/A. / 请补充框架版本、运行时、引擎版本或项目上下文；如不适用请填写 N/A。"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+blank_issues_enabled: false
+contact_links:
+  - name: "Search Existing Issues / 搜索现有 Issues"
+    url: "https://github.com/GeWuYou/GFramework/issues?q=is%3Aissue"
+    about: "Check whether your topic has already been reported or discussed. / 先确认是否已有相同问题或讨论。"
+  - name: "Read Contribution Guide / 阅读贡献指南"
+    url: "https://github.com/GeWuYou/GFramework/blob/main/docs/zh-CN/contributing.md"
+    about: "Review issue and pull request expectations before submitting. / 提交前先阅读 Issue 与 PR 的协作约定。"
+  - name: "Browse Documentation / 查看文档"
+    url: "https://github.com/GeWuYou/GFramework/tree/main/docs/zh-CN"
+    about: "Read docs, tutorials, and troubleshooting pages first. / 先查看文档、教程与排障页面。"

.github/actions/validate-pat/action.yml

@@ -0,0 +1,69 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+name: Validate PAT
+description: Validate that the release PAT can access the repository and push tags.
+
+inputs:
+  pat-token:
+    description: Personal access token used by semantic-release.
+    required: true
+  repo-api-url:
+    description: GitHub repository API URL, for example https://api.github.com/repos/owner/repo.
+    required: true
+  repository:
+    description: Repository slug used in error messages.
+    required: true
+  missing-token-message:
+    description: Error message emitted when the PAT is absent.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Validate PAT can push
+      shell: bash
+      env:
+        PAT_TOKEN: ${{ inputs.pat-token }}
+        REPO_API_URL: ${{ inputs.repo-api-url }}
+        REPOSITORY: ${{ inputs.repository }}
+        MISSING_TOKEN_MESSAGE: ${{ inputs.missing-token-message }}
+      run: |
+        if [ -z "${PAT_TOKEN}" ]; then
+          echo "::error::${MISSING_TOKEN_MESSAGE}"
+          exit 1
+        fi
+
+        response_file="$(mktemp)"
+        trap 'rm -f "${response_file}"' EXIT
+
+        status_code="$(
+          curl -sS -o "${response_file}" -w "%{http_code}" \
+            -H "Authorization: Bearer ${PAT_TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            "${REPO_API_URL}"
+        )"
+
+        case "${status_code}" in
+          200)
+            # The repository endpoint returns 200 for read-only tokens as well.
+            # semantic-release still performs a remote push probe, so require push permission here.
+            push_ok="$(jq -r '.permissions.push // false' "${response_file}")"
+            if [ "${push_ok}" != "true" ]; then
+              echo "::error::PAT_TOKEN can read ${REPOSITORY} but lacks push permission. semantic-release requires contents:write."
+              cat "${response_file}"
+              exit 1
+            fi
+            ;;
+          401|403)
+            echo "::error::PAT_TOKEN is invalid or lacks access to ${REPOSITORY} (HTTP ${status_code})."
+            cat "${response_file}"
+            exit 1
+            ;;
+          *)
+            echo "::error::Failed to validate PAT_TOKEN against ${REPO_API_URL} (HTTP ${status_code})."
+            cat "${response_file}"
+            exit 1
+            ;;
+        esac

.github/cliff.toml

@@ -0,0 +1,99 @@
+[remote.github]
+owner = "GeWuYou"
+repo = "GFramework"
+
+[changelog]
+header = ""
+
+body = """
+{%- macro remote_url() -%}
+https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
+{%- endmacro -%}
+
+{% macro has_release_highlight(commit) -%}
+{%- set highlighted = false -%}
+{%- if commit.remote and commit.remote.pr_labels -%}
+  {%- for label in commit.remote.pr_labels -%}
+    {%- if label == "release-highlight" or label == "highlight" -%}
+      {%- set highlighted = true -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+{%- if not highlighted and commit.footers -%}
+  {%- for footer in commit.footers -%}
+    {%- if footer.token == "Release-Highlight" and footer.value | trim == "true" -%}
+      {%- set highlighted = true -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+{{ highlighted }}
+{%- endmacro %}
+
+{% macro print_commit(commit) -%}
+- {{ commit.message | split(pat="\n") | first | trim | upper_first }}{% if commit.remote and commit.remote.username %} by @{{ commit.remote.username }}{% elif commit.author.name %} by {{ commit.author.name }}{% endif %}{% if commit.remote and commit.remote.pr_number %} in [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }}){% endif %}
+{%- endmacro %}
+
+{% if version -%}
+## {{ version }} ({{ timestamp | date(format="%Y-%m-%d") }})
+{% else -%}
+## 未发布
+{% endif %}
+
+{% set highlights = commits | filter(attribute="breaking", value=true) %}
+{% for commit in commits -%}
+  {% if self::has_release_highlight(commit=commit) == "true" -%}
+    {% set_global highlights = highlights | concat(with=commit) -%}
+  {% endif -%}
+{% endfor -%}
+
+{% if highlights | length > 0 -%}
+## 重点条目
+{% for commit in highlights -%}
+{{ self::print_commit(commit=commit) }}
+{% endfor %}
+
+{% endif -%}
+
+{% if commits | length > 0 -%}
+## What's Changed
+
+{% for group, commits in commits | group_by(attribute="group") -%}
+### {{ group | striptags | trim }}
+{% for commit in commits -%}
+{{ self::print_commit(commit=commit) }}
+{% endfor %}
+
+{% endfor -%}
+{% endif -%}
+
+{% if previous and previous.version and version -%}
+Full Changelog: [{{ previous.version }}...{{ version }}]({{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }})
+{% endif -%}
+"""
+
+footer = ""
+
+[git]
+conventional_commits = true
+filter_unconventional = true
+split_commits = false
+protect_breaking_commits = false
+sort_commits = "oldest"
+
+commit_parsers = [
+  { message = ".*\\[skip changelog\\].*", skip = true },
+  { body = ".*\\[skip changelog\\].*", skip = true },
+  { message = "^feat", group = "<!-- 0 -->✨ 新功能" },
+  { message = "^fix", group = "<!-- 1 -->🐛 Bug 修复" },
+  { message = "^perf", group = "<!-- 2 -->⚡ 优化" },
+  { message = "^refactor", group = "<!-- 2 -->⚡ 优化" },
+  { message = "^docs", group = "<!-- 3 -->📝 文档/其他" },
+  { message = "^test", group = "<!-- 3 -->📝 文档/其他" },
+  { message = "^chore", group = "<!-- 3 -->📝 文档/其他" },
+  { message = "^build", group = "<!-- 3 -->📝 文档/其他" },
+  { message = "^ci", group = "<!-- 3 -->📝 文档/其他" },
+  { message = "^style", group = "<!-- 3 -->📝 文档/其他" }
+]
+
+[git.github]
+commits = true

.github/dependabot.yml

@@ -1,3 +1,6 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
 version: 2
 updates:
   # ===== NuGet 依赖（所有项目）=====

.github/workflows/auto-tag.yml

@@ -1,64 +1,187 @@
-name: Auto Increment Version and Tag
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+name: Semantic Release Version and Tag
 
 on:
-  workflow_run:
-    workflows: ["CI - Build & Test"]
-    types:
-      - completed
   workflow_dispatch:
+
 concurrency:
-  group: auto-tag-main
+  group: semantic-release-main
   cancel-in-progress: false
 
 jobs:
-  auto-tag:
+  preview:
     if: >
-      github.ref == 'refs/heads/main' &&
-      (
-        (
-          github.event_name == 'workflow_run' &&
-          github.event.workflow_run.conclusion == 'success' &&
-          contains(github.event.workflow_run.head_commit.message, '[release ci]')
-        )
-        ||
-        github.event_name == 'workflow_dispatch'
-      )
-    
+      github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     permissions:
-      contents: write
+      contents: read
+      pull-requests: read
     outputs:
-      tagged: ${{ steps.create_tag.outcome == 'success' }}
+      published: ${{ steps.semantic_release.outputs.new_release_published }}
+      last_tag: ${{ steps.semantic_release.outputs.last_release_git_tag }}
+      next_version: ${{ steps.semantic_release.outputs.new_release_version }}
+      next_tag: ${{ steps.semantic_release.outputs.new_release_git_tag }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
           persist-credentials: false
+          ref: ${{ github.sha }}
 
-      - name: Get next version
-        id: version
-        run: |
-          LATEST_TAG=$(git tag --list "v*" --sort=-v:refname | head -n 1)
-          LATEST_TAG=${LATEST_TAG:-v0.0.0}
-          VERSION=${LATEST_TAG#v}
-          IFS=. read MAJOR MINOR PATCH <<< "$VERSION"
-          PATCH=$((PATCH+1))
-          echo "new_tag=v$MAJOR.$MINOR.$PATCH" >> $GITHUB_OUTPUT
+      # semantic-release 在 dry-run 中仍会执行一次 git push --dry-run 权限探测。
+      # 这里提前要求与正式 release 相同的 PAT，避免 github-actions[bot] 因只读上下文触发误导性的 403。
+      - name: Validate PAT token
+        uses: ./.github/actions/validate-pat
+        with:
+          pat-token: ${{ secrets.PAT_TOKEN }}
+          repo-api-url: ${{ github.api_url }}/repos/${{ github.repository }}
+          repository: ${{ github.repository }}
+          missing-token-message: PAT_TOKEN is required because semantic-release preview performs a git push --dry-run permission check.
 
-      - name: Create tag
+      # preview 始终先运行，用于给当前 SHA 生成待发布版本预览。
+      - name: Semantic release preview
+        id: semantic_release
+        uses: cycjimmy/semantic-release-action@v6
+        with:
+          dry_run: true
+          ci: false
+          extra_plugins: |
+            conventional-changelog-conventionalcommits@9.1.0
         env:
-          PAT: ${{ secrets.PAT_TOKEN }}
-          TAG: ${{ steps.version.outputs.new_tag }}
+          GITHUB_TOKEN: ${{ secrets.PAT_TOKEN }}
+
+      - name: Show preview result
         run: |
-          set -e
-          git config user.name "GitHub Action"
-          git config user.email "action@github.com"
+          echo "published=${{ steps.semantic_release.outputs.new_release_published }}"
+          echo "last_tag=${{ steps.semantic_release.outputs.last_release_git_tag }}"
+          echo "next_version=${{ steps.semantic_release.outputs.new_release_version }}"
+          echo "next_tag=${{ steps.semantic_release.outputs.new_release_git_tag }}"
 
-          if git show-ref --tags --verify --quiet "refs/tags/$TAG"; then
-            echo "Tag $TAG already exists, skipping"
-            exit 0
-          fi
+      - name: Generate preview release notes
+        if: ${{ steps.semantic_release.outputs.new_release_published == 'true' }}
+        id: cliff_preview
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: .github/cliff.toml
+          args: >-
+            -vv --unreleased --strip header
+            --tag "${{ steps.semantic_release.outputs.new_release_git_tag }}"
+        env:
+          OUTPUT: PREVIEW_RELEASE_NOTES.md
+          GITHUB_REPO: ${{ github.repository }}
+          GITHUB_TOKEN: ${{ github.token }}
 
-          git tag -a "$TAG" -m "Auto tag $TAG"
-          git push "https://x-access-token:${PAT}@github.com/${{ github.repository }}.git" "$TAG"
+      - name: Write preview summary
+        env:
+          RELEASE_PUBLISHED: ${{ steps.semantic_release.outputs.new_release_published }}
+          CLIFF_RELEASE_NOTES: ${{ steps.cliff_preview.outputs.content }}
+        run: |
+          {
+            echo "## Release Preview"
+            echo
+            echo "- Commit: \`${{ github.sha }}\`"
+            echo "- Release needed: \`${{ steps.semantic_release.outputs.new_release_published }}\`"
+            echo "- Last tag: \`${{ steps.semantic_release.outputs.last_release_git_tag }}\`"
+            echo "- Next version: \`${{ steps.semantic_release.outputs.new_release_version }}\`"
+            echo "- Next tag: \`${{ steps.semantic_release.outputs.new_release_git_tag }}\`"
+            echo "- Preview auth: uses \`PAT_TOKEN\` because semantic-release dry-run still performs a remote push permission probe."
+            echo "- Snapshot semantics: this preview is pinned to dispatch SHA \`${{ github.sha }}\`; commits added to \`main\` after the run starts are not included."
+            if [ "${RELEASE_PUBLISHED}" = "true" ] && [ -n "${CLIFF_RELEASE_NOTES}" ]; then
+              echo
+              echo "### 候选发布说明"
+              echo
+              printf '%s\n' "${CLIFF_RELEASE_NOTES}"
+            fi
+            echo
+            echo "If the version looks correct, approve the \`release-approval\` environment to continue."
+          } >> "${GITHUB_STEP_SUMMARY}"
+
+  release:
+    if: >
+      github.ref == 'refs/heads/main' &&
+      needs.preview.result == 'success' &&
+      needs.preview.outputs.published == 'true'
+    needs:
+      - preview
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: read
+    environment:
+      name: release-approval
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ github.sha }}
+
+      - name: Validate PAT token
+        uses: ./.github/actions/validate-pat
+        with:
+          pat-token: ${{ secrets.PAT_TOKEN }}
+          repo-api-url: ${{ github.api_url }}/repos/${{ github.repository }}
+          repository: ${{ github.repository }}
+          missing-token-message: PAT_TOKEN is required because a tag created with GITHUB_TOKEN will not trigger publish.yml.
+
+      - name: Semantic release
+        id: semantic_release
+        uses: cycjimmy/semantic-release-action@v6
+        with:
+          dry_run: false
+          extra_plugins: |
+            conventional-changelog-conventionalcommits@9.1.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.PAT_TOKEN }}
+
+      - name: Show release result
+        run: |
+          echo "published=${{ steps.semantic_release.outputs.new_release_published }}"
+          echo "preview_last_tag=${{ needs.preview.outputs.last_tag }}"
+          echo "preview_next_version=${{ needs.preview.outputs.next_version }}"
+          echo "preview_next_tag=${{ needs.preview.outputs.next_tag }}"
+          echo "last_tag=${{ steps.semantic_release.outputs.last_release_git_tag }}"
+          echo "next_version=${{ steps.semantic_release.outputs.new_release_version }}"
+          echo "next_tag=${{ steps.semantic_release.outputs.new_release_git_tag }}"
+
+      - name: Generate published release notes
+        if: ${{ steps.semantic_release.outputs.new_release_published == 'true' }}
+        id: cliff_release
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: .github/cliff.toml
+          args: >-
+            -vv --latest --strip header
+        env:
+          OUTPUT: PUBLISHED_RELEASE_NOTES.md
+          GITHUB_REPO: ${{ github.repository }}
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Write release summary
+        env:
+          RELEASE_PUBLISHED: ${{ steps.semantic_release.outputs.new_release_published }}
+          CLIFF_RELEASE_NOTES: ${{ steps.cliff_release.outputs.content }}
+        run: |
+          {
+            echo "## Release Publish"
+            echo
+            echo "- Commit: \`${{ github.sha }}\`"
+            echo "- Preview last tag: \`${{ needs.preview.outputs.last_tag }}\`"
+            echo "- Preview next version: \`${{ needs.preview.outputs.next_version }}\`"
+            echo "- Preview next tag: \`${{ needs.preview.outputs.next_tag }}\`"
+            echo "- Published: \`${{ steps.semantic_release.outputs.new_release_published }}\`"
+            echo "- Last tag: \`${{ steps.semantic_release.outputs.last_release_git_tag }}\`"
+            echo "- Next version: \`${{ steps.semantic_release.outputs.new_release_version }}\`"
+            echo "- Next tag: \`${{ steps.semantic_release.outputs.new_release_git_tag }}\`"
+            echo "- Snapshot semantics: this publish run still uses dispatch SHA \`${{ github.sha }}\`; commits added to \`main\` after the preview started are excluded."
+            if [ "${RELEASE_PUBLISHED}" = "true" ] && [ -n "${CLIFF_RELEASE_NOTES}" ]; then
+              echo
+              echo "### 已发布说明"
+              echo
+              printf '%s\n' "${CLIFF_RELEASE_NOTES}"
+            fi
+          } >> "${GITHUB_STEP_SUMMARY}"

.github/workflows/benchmark.yml

@@ -0,0 +1,71 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+name: Benchmark
+
+on:
+  workflow_dispatch:
+    inputs:
+      benchmark_filter:
+        description: '可选的 BenchmarkDotNet 过滤器；留空时仅执行 benchmark 项目 Release build'
+        required: false
+        default: ''
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark:
+    name: Benchmark Build Or Run
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET 10
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Cache NuGet packages
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.nuget/packages
+            ~/.local/share/NuGet
+          key: ${{ runner.os }}-nuget-benchmarks-${{ hashFiles('GFramework.Cqrs.Benchmarks/*.csproj', 'GFramework.Cqrs/*.csproj', 'GFramework.Cqrs.Abstractions/*.csproj', 'GFramework.Core/*.csproj', 'GFramework.Core.Abstractions/*.csproj', '**/nuget.config') }}
+
+      - name: Restore benchmark project
+        run: dotnet restore GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj
+
+      - name: Build benchmark project
+        run: dotnet build GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj -c Release --no-restore
+
+      - name: Report build-only mode
+        if: ${{ inputs.benchmark_filter == '' }}
+        run: |
+          echo "No benchmark filter provided."
+          echo "Workflow completed after validating the benchmark project build."
+
+      - name: Run filtered benchmarks
+        if: ${{ inputs.benchmark_filter != '' }}
+        env:
+          BENCHMARK_FILTER: ${{ inputs.benchmark_filter }}
+        run: |
+          set -euo pipefail
+          dotnet run --project GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj -c Release --no-build -- \
+            --filter "$BENCHMARK_FILTER"
+
+      - name: Upload BenchmarkDotNet artifacts
+        if: ${{ always() && inputs.benchmark_filter != '' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: benchmark-artifacts
+          path: |
+            BenchmarkDotNet.Artifacts/**
+            GFramework.Cqrs.Benchmarks/bin/Release/net10.0/BenchmarkDotNet.Artifacts/**
+          if-no-files-found: ignore

.github/workflows/ci.yml

@@ -1,15 +1,17 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
 # CI/CD工作流配置：构建和测试.NET项目
-# 该工作流在push到main/master分支或创建pull request时触发
+# 该工作流仅在创建或更新面向任意分支的 pull request 时触发
 name: CI - Build & Test
 
 on:
-  push:
-    branches: [ main, master ]
   pull_request:
-    branches: [ main, master ]
+    branches: [ '**' ]
 
 permissions:
   contents: read
+  pull-requests: write
   security-events: write
 
 jobs:
@@ -29,6 +31,13 @@ jobs:
       - name: Validate C# naming
         run: bash scripts/validate-csharp-naming.sh
 
+      # 校验仓库维护源码是否包含 Apache-2.0 文件头声明
+      - name: Validate license headers
+        run: python3 scripts/license-header.py --check
+
+      - name: Validate runtime-generator boundaries
+        run: python3 scripts/validate-runtime-generator-boundaries.py
+
       # 缓存MegaLinter
       - name: Cache MegaLinter
         uses: actions/cache@v5
@@ -64,14 +73,14 @@ jobs:
       # 使用 TruffleHog 工具扫描代码库中的敏感信息泄露，如API密钥、密码等
       # 该步骤会比较基础分支和当前提交之间的差异，检测新增内容中是否包含敏感数据
       - name: TruffleHog OSS
-        uses: trufflesecurity/trufflehog@v3.94.1
+        uses: trufflesecurity/trufflehog@v3.95.2
         with:
           # 扫描路径，. 表示扫描整个仓库
           path: .
           # 基础提交哈希，用于与当前提交进行比较
-          base: ${{ github.event.before }}
+          base: ${{ github.event.pull_request.base.sha }}
           # 当前提交哈希，作为扫描的目标版本
-          head: ${{ github.sha }}
+          head: ${{ github.event.pull_request.head.sha }}
 
   # 构建和测试 job（并行执行）
   build-and-test:
@@ -119,46 +128,107 @@ jobs:
 
       # 执行NuGet包恢复操作
       - name: Restore
-        run: dotnet restore
+        run: dotnet restore GFramework.sln
       # 恢复.NET本地工具
       - name: Restore .NET tools
         run: dotnet tool restore
+
+      - name: Setup Node.js 20
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.2.15
+
+      - name: Install config tool dependencies
+        working-directory: tools/gframework-config-tool
+        run: bun install
+
+      - name: Run config tool tests
+        working-directory: tools/gframework-config-tool
+        run: bun run test
         
       # 构建项目，使用Release配置且跳过恢复步骤
       - name: Build
-        run: dotnet build -c Release --no-restore
+        run: dotnet build GFramework.sln -c Release --no-restore
+
+      - name: Pack published modules
+        run: |
+          rm -rf ./packages
+          dotnet pack GFramework.sln \
+            -c Release \
+            --no-build \
+            --no-restore \
+            -o ./packages \
+            -p:IncludeSymbols=false
+
+      - name: Validate packed modules
+        run: bash scripts/validate-packed-modules.sh ./packages
 
       # 运行单元测试，输出TRX格式结果到TestResults目录
-      # 在同一个 step 中并发执行所有测试以加快速度
+      # 顺序执行各测试项目，避免并发 dotnet test 进程导致“TRX 全绿但 step 仍返回失败”的假红状态
       - name: Test All Projects
+        id: test_all_projects
         run: |
-          dotnet test GFramework.Core.Tests \
-            -c Release \
-            --no-build \
-            --logger "trx;LogFileName=core-$RANDOM.trx" \
-            --results-directory TestResults &
+          set -euo pipefail
+          mkdir -p TestResults
 
-          dotnet test GFramework.Game.Tests \
-            -c Release \
-            --no-build \
-            --logger "trx;LogFileName=game-$RANDOM.trx" \
-            --results-directory TestResults &
+          test_projects=(
+            "GFramework.Core.Tests/GFramework.Core.Tests.csproj:core"
+            "GFramework.Game.Tests/GFramework.Game.Tests.csproj:game"
+            "GFramework.SourceGenerators.Tests/GFramework.SourceGenerators.Tests.csproj:sg"
+            "GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj:cqrs"
+            "GFramework.Ecs.Arch.Tests/GFramework.Ecs.Arch.Tests.csproj:ecs-arch"
+            "GFramework.Godot.Tests/GFramework.Godot.Tests.csproj:godot"
+            "GFramework.Godot.SourceGenerators.Tests/GFramework.Godot.SourceGenerators.Tests.csproj:godot-sg"
+          )
 
-          dotnet test GFramework.SourceGenerators.Tests \
-            -c Release \
-            --no-build \
-            --logger "trx;LogFileName=sg-$RANDOM.trx" \
-            --results-directory TestResults &
+          failed=0
+          failed_projects=()
+          failed_log_paths=()
 
-          dotnet test GFramework.Ecs.Arch.Tests \
-            -c Release \
-            --no-build \
-            --logger "trx;LogFileName=ecs-arch-$RANDOM.trx" \
-            --results-directory TestResults &
+          for entry in "${test_projects[@]}"; do
+            project="${entry%%:*}"
+            name="${entry##*:}"
+            log_path="TestResults/${name}.console.log"
+
+            echo "::group::dotnet test $project"
+            if ! dotnet test "$project" \
+              -c Release \
+              --no-build \
+              --logger "trx;LogFileName=${name}.trx" \
+              --results-directory TestResults \
+              2>&1 | tee "$log_path"; then
+              failed=1
+              failed_projects+=("$project")
+              failed_log_paths+=("$log_path")
+              echo "::error title=Test project failed::$project returned a non-zero exit code."
+            fi
+            echo "::endgroup::"
+          done
+
+          if [ "$failed" -eq 1 ]; then
+            printf 'Failed test projects:\n'
+            printf '  %s\n' "${failed_projects[@]}"
+          fi
+
+          {
+            echo "failed=$failed"
+            echo "failed_projects<<EOF"
+            if [ "${#failed_projects[@]}" -gt 0 ]; then
+              printf '%s\n' "${failed_projects[@]}"
+            fi
+            echo "EOF"
+            echo "failed_log_paths<<EOF"
+            if [ "${#failed_log_paths[@]}" -gt 0 ]; then
+              printf '%s\n' "${failed_log_paths[@]}"
+            fi
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
 
-          # 等待所有后台测试完成
-          wait
-          
       - name: Generate CTRF report
         run: |
           mkdir -p ctrf
@@ -173,6 +243,20 @@ jobs:
               -d ctrf \
               -f "$name.json"
           done
+
+      - name: Run GFramework.Godot.Tests Diagnostics
+        if: always() && contains(steps.test_all_projects.outputs.failed_projects, 'GFramework.Godot.Tests/GFramework.Godot.Tests.csproj')
+        continue-on-error: true
+        run: |
+          mkdir -p TestResults
+          dotnet test GFramework.Godot.Tests/GFramework.Godot.Tests.csproj \
+            -c Release \
+            --no-build \
+            --blame-crash \
+            --diag TestResults/godot-testhost-diag.log \
+            --logger "trx;LogFileName=godot-diagnostic.trx" \
+            --results-directory TestResults \
+            2>&1 | tee TestResults/godot-diagnostic.console.log
       
       
       # 生成并发布测试报告，无论测试成功或失败都会执行
@@ -188,7 +272,7 @@ jobs:
         with:
           report-path: './ctrf/*.json'
           github-report: true
-          pull-request-report: true
+          pull-request-report: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
           summary-delta-report: true
           insights-report: true
           flaky-rate-report: true
@@ -199,3 +283,22 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         if: always()
+
+      - name: Fail if any test project failed
+        if: always() && steps.test_all_projects.outputs.failed == '1'
+        env:
+          FAILED_PROJECTS: ${{ steps.test_all_projects.outputs.failed_projects }}
+          FAILED_LOG_PATHS: ${{ steps.test_all_projects.outputs.failed_log_paths }}
+        run: |
+          echo "The following test projects returned non-zero exit codes:"
+          printf '%s\n' "$FAILED_PROJECTS"
+          echo
+          echo "Captured dotnet test output:"
+          while IFS= read -r log_path; do
+            if [ -n "$log_path" ] && [ -f "$log_path" ]; then
+              echo "--- BEGIN $log_path ---"
+              cat "$log_path"
+              echo "--- END $log_path ---"
+            fi
+          done <<< "$FAILED_LOG_PATHS"
+          exit 1

.github/workflows/codeql.yml

@@ -1,17 +1,17 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
 # GitHub Actions工作流配置：CodeQL静态代码分析
 # 该工作流用于对C#项目进行安全漏洞和代码质量分析
 name: "CodeQL"
 
 # 触发事件配置
 # 在以下情况下触发工作流：
-# 1. 推送到main分支时
-# 2. 针对main分支的拉取请求时  
-# 3. 每天凌晨2点执行一次
+# 1. 针对任意分支的拉取请求时
+# 2. 每天凌晨2点执行一次
 on:
-  push:
-    branches: [ "main" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ '**' ]
   schedule:
     - cron: '0 2 * * *'
 

.github/workflows/license-compliance.yml

@@ -1,3 +1,6 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
 name: License Compliance (Feluda)
 
 on:
@@ -5,6 +8,10 @@ on:
     tags:
       - '*'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
 
@@ -58,6 +65,7 @@ jobs:
       #   with: 配置上传的具体内容
       #     name: 工件名称，用于标识上传的文件集合
       #     path: 指定需要上传的文件路径列表（支持多行格式）
+      #       third-party-licenses/**: 手工维护的参考源码许可证原文
       - name: Upload compliance artifacts
         uses: actions/upload-artifact@v7
         with:
@@ -65,6 +73,7 @@ jobs:
           path: |
             NOTICE
             THIRD_PARTY_LICENSES.md
+            third-party-licenses/**
             sbom.spdx.json
             sbom.cyclonedx.json
             sbom-spdx-validation.txt
@@ -75,15 +84,17 @@ jobs:
       # 压缩包中包含以下文件：
       #   - NOTICE: 项目声明文件
       #   - THIRD_PARTY_LICENSES.md: 第三方许可证列表
+      #   - third-party-licenses/: 手工维护的参考源码许可证原文
       #   - sbom.spdx.json: SPDX 格式的软件物料清单
       #   - sbom.cyclonedx.json: CycloneDX 格式的软件物料清单
       #   - sbom-spdx-validation.txt: SPDX 格式验证结果
       #   - sbom-cyclonedx-validation.txt: CycloneDX 格式验证结果
       - name: Package compliance bundle
         run: |
-          zip license-compliance.zip \
+          zip -r license-compliance.zip \
             NOTICE \
             THIRD_PARTY_LICENSES.md \
+            third-party-licenses \
             sbom.spdx.json \
             sbom.cyclonedx.json \
             sbom-spdx-validation.txt \
@@ -102,7 +113,7 @@ jobs:
       #   env: 设置环境变量
       #     GITHUB_TOKEN: GitHub 访问令牌，用于授权发布操作
       - name: Upload compliance assets to GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ github.ref_name }}
           files: |
@@ -114,4 +125,4 @@ jobs:
             sbom-cyclonedx-validation.txt
             license-compliance.zip
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}

.github/workflows/license-header-fix.yml

@@ -0,0 +1,54 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+# 维护者手动触发的 Apache-2.0 文件头修复流程。
+name: License Header Fix
+
+on:
+  workflow_dispatch:
+    inputs:
+      base_branch:
+        description: Branch to fix and target with the generated pull request.
+        required: true
+        default: main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  fix-license-headers:
+    name: Create license header fix PR
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout target branch
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.base_branch }}
+
+      - name: Add missing license headers
+        run: python3 scripts/license-header.py --fix
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          base: ${{ inputs.base_branch }}
+          branch: chore/license-headers-${{ github.run_id }}
+          delete-branch: true
+          commit-message: |
+            chore(license): 补齐 Apache-2.0 文件头
+
+            - 补充缺失源文件许可证声明
+            - 更新文件头治理校验结果
+          title: "chore(license): 补齐 Apache-2.0 文件头"
+          body: |
+            ## Summary
+
+            - 补齐仓库维护源码和配置文件缺失的 Apache-2.0 文件头
+            - 使用 `scripts/license-header.py --fix` 生成本次修复
+
+            ## Validation
+
+            - `python3 scripts/license-header.py --check`

.github/workflows/publish-docs.yml

@@ -1,3 +1,6 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
 # 工作流名称：Publish Docs
 # 该工作流用于在推送标签或手动触发时构建并部署文档到 GitHub Pages
 
@@ -50,6 +53,10 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
+      # 按 GitHub Pages 官方流程初始化部署元数据。
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+
       # 安装 Bun 运行时
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -70,11 +77,30 @@ jobs:
       - name: Make docs LLM ready
         uses: demodrive-ai/llms-txt-action@v1
         with:
-          docs_dir: docs/.vitepress/dist 
+          docs_dir: docs/.vitepress/dist
+          sitemap_path: sitemap.xml
+          skip_llms_txt: 'false'
+          skip_llms_full_txt: 'false'
+          skip_md_files: 'false'
+
+      # 在上传前校验 LLM 索引产物，避免部署出“步骤成功但文件缺失”的 Pages 站点。
+      - name: Verify LLM artifacts
+        run: |
+          test -f docs/.vitepress/dist/sitemap.xml
+          test -f docs/.vitepress/dist/llms.txt
+          test -f docs/.vitepress/dist/llms-full.txt
+
+          md_count="$(find docs/.vitepress/dist -type f -name '*.md' | wc -l)"
+          if [ "$md_count" -eq 0 ]; then
+            echo "Expected llms-txt-action to generate page-level markdown files, but none were found."
+            exit 1
+          fi
+
+          echo "Generated $md_count markdown files for LLM ingestion."
       
       # 上传构建产物作为 Pages 部署工件
       - name: Upload Pages Artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: docs/.vitepress/dist
 

.github/workflows/publish-vscode-extension.yml

@@ -0,0 +1,97 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+name: Publish VS Code Extension
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Extension version to publish, for example 0.1.0. Leave empty to use package.json or the pushed tag.
+        required: false
+        type: string
+      publish_to_marketplace:
+        description: Publish to the Visual Studio Marketplace after packaging.
+        required: true
+        type: boolean
+        default: true
+  push:
+    tags:
+      - 'gframework-config-tool-v*'
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Package And Publish Marketplace Extension
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: tools/gframework-config-tool
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js 20
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.2.15
+
+      - name: Determine extension version
+        id: version
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          VERSION="${PACKAGE_VERSION}"
+
+          if [[ "${GITHUB_REF:-}" == refs/tags/gframework-config-tool-v* ]]; then
+            VERSION="${GITHUB_REF#refs/tags/gframework-config-tool-v}"
+          elif [[ -n "${{ inputs.version || '' }}" ]]; then
+            VERSION="${{ inputs.version }}"
+          fi
+
+          echo "Resolved extension version: ${VERSION}"
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+
+      - name: Install extension dependencies
+        run: bun install
+
+      - name: Synchronize package.json version
+        shell: bash
+        run: |
+          set -euo pipefail
+          node -e "const fs=require('fs'); const path='package.json'; const data=JSON.parse(fs.readFileSync(path,'utf8')); data.version='${{ steps.version.outputs.version }}'; fs.writeFileSync(path, JSON.stringify(data, null, 2) + '\n');"
+
+      - name: Run extension tests
+        run: bun run test
+
+      - name: Package VSIX
+        run: |
+          set -euo pipefail
+          mkdir -p ../../artifacts
+          bun run package:vsix -- --out "../../artifacts/gframework-config-tool-${{ steps.version.outputs.version }}.vsix"
+
+      - name: Upload VSIX artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: gframework-config-tool-vsix
+          path: artifacts/gframework-config-tool-${{ steps.version.outputs.version }}.vsix
+          if-no-files-found: error
+
+      - name: Publish to Visual Studio Marketplace
+        if: github.event_name == 'push' || inputs.publish_to_marketplace
+        env:
+          VSCE_PAT: ${{ secrets.VSCE_PAT }}
+        run: bun run publish:marketplace

.github/workflows/publish.yml

@@ -1,30 +1,40 @@
-# 发布工作流（NuGet + GitHub Release）
-# 
-# 功能：当推送标签时自动构建、打包并发布到 NuGet.org 和 GitHub Release
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+# 发布工作流（NuGet + GitHub Packages + GitHub Release）
+#
+# 功能：当推送标签时自动构建、打包，并将相同产物并发发布到 NuGet.org 与 GitHub Packages，
+#       最后创建 GitHub Release。
 # 触发条件：推送任何标签（如 v1.0.0 或 1.0.0）
 # 权限：允许写入内容、包和使用 OIDC 身份验证
-name: Publish (NuGet + GitHub Release)
+name: Publish (NuGet + GitHub Packages + GitHub Release)
 
-# 触发：推送 tag 时触发（例如 v1.0.0 或 1.0.0）
 on:
   push:
     tags:
       - '*'
 
-# 顶级权限：允许创建 release、写 packages，并允许 id-token（OIDC）
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
   packages: write
   id-token: write
 
 jobs:
-  build-and-publish:
+  build-pack:
+    name: Build And Pack
     runs-on: ubuntu-latest
 
     permissions:
+      contents: read
+      packages: read
       id-token: write
-      contents: write
-      packages: write
+
+    outputs:
+      package_version: ${{ steps.tag_version.outputs.version }}
 
     steps:
       - name: Checkout repository (at tag)
@@ -38,19 +48,17 @@ jobs:
         with:
           dotnet-version: 10.0.x
 
-      - name: Install unzip (for reading .nuspec from .nupkg)
-        run: sudo apt-get update && sudo apt-get install -y unzip
       - name: Cache NuGet packages
         uses: actions/cache@v5
         with:
           path: ~/.nuget/packages
           key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj') }}
+
       - name: Restore dependencies
-        run: dotnet restore
-      
-      # 从 GitHub 引用中提取标签版本
-      # 提取逻辑：去除 refs/tags/ 前缀，然后去除 v/V 前缀
-      # 输出：version - 处理后的版本号
+        run: dotnet restore GFramework.sln
+
+      # 从 GitHub 引用中提取标签版本。
+      # 提取逻辑：去除 refs/tags/ 前缀，然后去除 v/V 前缀。
       - name: Determine tag version
         id: tag_version
         run: |
@@ -60,26 +68,58 @@ jobs:
           VERSION=${TAG#v}
           VERSION=${VERSION#V}
           echo "tag='$TAG' -> version='$VERSION'"
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
       - name: Pack (use tag version)
         run: |
           set -e
           echo "Packing with version=${{ steps.tag_version.outputs.version }}"
-          dotnet pack -c Release -o ./packages -p:PackageVersion=${{ steps.tag_version.outputs.version }} -p:IncludeSymbols=false
-      # 上传许可证合规相关的工件文件，包括通知文件、第三方许可证、SBOM文件及验证结果
-      - name: Upload compliance artifacts
+          dotnet pack GFramework.sln \
+            -c Release \
+            --no-restore \
+            -o ./packages \
+            -p:PackageVersion=${{ steps.tag_version.outputs.version }} \
+            -p:IncludeSymbols=false
+
+      - name: Validate packed modules
+        run: bash scripts/validate-packed-modules.sh ./packages
+
+      - name: Validate runtime-generator package boundaries
+        run: python3 scripts/validate-runtime-generator-boundaries.py --package-dir ./packages
+
+      - name: Show packages
+        run: ls -la ./packages || true
+
+      # 上传 nupkg 工件，供多个发布 job 复用，避免重复打包。
+      - name: Upload package artifacts
         uses: actions/upload-artifact@v7
         with:
-          name: license-compliance
-          path: |
-            NOTICE
-            THIRD_PARTY_LICENSES.md
-            sbom.spdx.json
-            sbom.cyclonedx.json
-            sbom-spdx-validation.txt
-            sbom-cyclonedx-validation.txt
-      - name: Show packages
+          name: packages
+          path: ./packages/*.nupkg
+
+  publish-nuget:
+    name: Publish To NuGet.org
+    runs-on: ubuntu-latest
+    needs: build-pack
+
+    permissions:
+      contents: read
+      packages: read
+      id-token: write
+
+    steps:
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Download package artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: packages
+          path: ./packages
+
+      - name: Show downloaded packages
         run: ls -la ./packages || true
 
       - name: NuGet login (OIDC → temporary API key)
@@ -88,9 +128,8 @@ jobs:
         with:
           user: ${{ secrets.NUGET_USER }}
 
-      # 将所有生成的包推送到 nuget.org
-      # 使用临时 API 密钥进行身份验证
-      # 跳过重复包的上传
+      # 将所有生成的包推送到 nuget.org。
+      # 使用临时 API 密钥进行身份验证，并跳过重复包上传。
       - name: Push all packages to nuget.org
         env:
           NUGET_API_KEY: ${{ steps.nuget_login.outputs.NUGET_API_KEY }}
@@ -110,58 +149,119 @@ jobs:
           if [ "$pushed_any" = false ]; then
             echo "No packages found to push."
           fi
-      
-      # 从 .nupkg 文件中提取版本信息
-      # 通过解压 .nupkg（zip 格式）并读取 .nuspec 文件来获取版本
-      # 输出：
-      #   package_file - 第一个找到的包文件路径
-      #   package_basename - 包文件的基本名称
-      #   version - 从 nuspec 中解析出的版本号
-      - name: Get Version and First Package Path
-        id: get_version
+
+  publish-github-packages:
+    name: Publish To GitHub Packages
+    runs-on: ubuntu-latest
+    needs: build-pack
+
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Download package artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: packages
+          path: ./packages
+
+      - name: Show downloaded packages
+        run: ls -la ./packages || true
+
+      # 使用仓库内建的 GITHUB_TOKEN 配置 GitHub Packages NuGet 源。
+      - name: Configure GitHub Packages source
         run: |
           set -e
-          PACKAGE_FILE=$(find ./packages -name "*.nupkg" | head -n 1 || true)
-          if [ -z "$PACKAGE_FILE" ]; then
-            echo "No .nupkg file found in ./packages"
-            exit 1
-          fi
-          # 从 .nupkg（zip）里读取 .nuspec 并提取 <version>
-          VERSION=$(unzip -p "$PACKAGE_FILE" '*.nuspec' 2>/dev/null | sed -n 's:.*<version>\(.*\)</version>.*:\1:p' | head -n1)
-          if [ -z "$VERSION" ]; then
-            echo "Failed to parse version from $PACKAGE_FILE"
-            exit 1
-          fi
-          BASENAME=$(basename "$PACKAGE_FILE")
-          echo "package_file=$PACKAGE_FILE" >> $GITHUB_OUTPUT
-          echo "package_basename=$BASENAME" >> $GITHUB_OUTPUT
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          dotnet nuget add source "https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json" \
+            --name github \
+            --username "${{ github.repository_owner }}" \
+            --password "${{ github.token }}" \
+            --store-password-in-clear-text
 
-      # 创建 GitHub Release
-      # 使用从包中提取的版本信息和当前标签创建发布
-      # 发布包含描述信息和版本详情
-      - name: Create GitHub Release and Upload Assets
-        uses: softprops/action-gh-release@v2
+      - name: Push all packages to GitHub Packages
+        run: |
+          set -e
+          pushed_any=false
+          for PKG in ./packages/*.nupkg; do
+            [ -f "$PKG" ] || continue
+            pushed_any=true
+            echo "Pushing $PKG to GitHub Packages..."
+            dotnet nuget push "$PKG" \
+              --source github \
+              --skip-duplicate
+          done
+          if [ "$pushed_any" = false ]; then
+            echo "No packages found to push."
+          fi
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs:
+      - build-pack
+      - publish-nuget
+      - publish-github-packages
+    if: ${{ always() && needs.build-pack.result == 'success' }}
+
+    permissions:
+      contents: write
+      packages: read
+      pull-requests: read
+
+    steps:
+      - name: Checkout repository (at tag)
+        uses: actions/checkout@v6
         with:
-          generate_release_notes: true
-          name: "Release ${{ github.ref_name }}"
-          body: |
-            Release created by CI for tag ${{ github.ref_name }}
-            Package version: ${{ steps.get_version.outputs.version }}
+          fetch-depth: 0
+          persist-credentials: true
 
-            ## Compliance
-            - NOTICE
-            - THIRD_PARTY_LICENSES
-            - SPDX & CycloneDX SBOM
+      - name: Download package artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: packages
+          path: ./packages
+
+      - name: Generate release notes
+        id: cliff_release
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: .github/cliff.toml
+          args: >-
+            -vv --latest --strip header
+        env:
+          OUTPUT: RELEASE_NOTES.md
+          GITHUB_REPO: ${{ github.repository }}
+          GITHUB_TOKEN: ${{ github.token }}
+
+      # 无论某一侧包源发布是否失败，都继续创建 Release。
+      # 合规工件由独立 workflow 生成，当前发布流不再假设这些文件在同一次运行中可用。
+      - name: Create GitHub Release and Upload Assets
+        uses: softprops/action-gh-release@v3
+        with:
+          name: "Release ${{ github.ref_name }}"
+          body_path: RELEASE_NOTES.md
           draft: false
           prerelease: false
           files: |
             ./packages/*.nupkg
-            NOTICE
-            THIRD_PARTY_LICENSES.md
-            sbom.spdx.json
-            sbom.cyclonedx.json
-            sbom-spdx-validation.txt
-            sbom-cyclonedx-validation.txt
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Write publish summary
+        env:
+          CLIFF_RELEASE_NOTES: ${{ steps.cliff_release.outputs.content }}
+        run: |
+          {
+            echo "## GitHub Release"
+            echo
+            echo "- Tag: \`${{ github.ref_name }}\`"
+            echo "- Package version: \`${{ needs.build-pack.outputs.package_version }}\`"
+            echo
+            printf '%s\n' "${CLIFF_RELEASE_NOTES}"
+          } >> "${GITHUB_STEP_SUMMARY}"

.gitignore

@@ -5,6 +5,8 @@ riderModule.iml
 /_ReSharper.Caches/
 GFramework.sln.DotSettings.user
 .idea/
+dotnet-home/
+scripts/__pycache__/
 # ai
 opencode.json
 .claude/settings.local.json
@@ -12,6 +14,15 @@ opencode.json
 .omc/
 docs/.omc/
 docs/.vitepress/cache/
-local-plan/
+ai-plan/*
+!ai-plan/README.md
+!ai-plan/public/
+ai-plan/public/*
+!ai-plan/public/README.md
+!ai-plan/public/**/
+!ai-plan/public/**/*.md
+ai-plan/private/
+ai-libs/
+.codex
 # tool
-.venv/
+.venv/

.mega-linter.yml

@@ -1,4 +1,7 @@
-# 配置文件用于设置代码质量检查工具的各项参数和规则
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+# 配置文件用于设置代码质量检查工具的各项参数和规则
 # 包含全局排除目录、启用/禁用的检查器、特定语言配置等设置
 
 APPLY_FIXES: none
@@ -45,6 +48,9 @@ ENABLE_LINTERS:
 # 设置 C# 代码风格检查的参数和验证级别
 # ========================
 CSHARP_DOTNET_FORMAT_ARGUMENTS:
+  # 仓库根目录同时存在 GFramework.sln 与 GFramework.csproj；
+  # 显式指定 workspace，避免 dotnet format 在 CI 中因自动探测歧义直接异常退出。
+  - "GFramework.sln"
   - "--severity"
   - "info"
   - "--verify-no-changes"
@@ -83,4 +89,3 @@ GITHUB_COMMENT_REPORTER: true
 PARALLEL: true
 SHOW_ELAPSED_TIME: true
 VALIDATE_ALL_CODEBASE: false
-

.releaserc.json

@@ -0,0 +1,129 @@
+{
+  "branches": [
+    "main"
+  ],
+  "tagFormat": "v${version}",
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [
+          {
+            "breaking": true,
+            "release": "major"
+          },
+          {
+            "revert": true,
+            "release": "patch"
+          },
+          {
+            "type": "feat",
+            "release": "minor"
+          },
+          {
+            "type": "fix",
+            "release": "patch"
+          },
+          {
+            "type": "perf",
+            "release": "patch"
+          },
+          {
+            "type": "refactor",
+            "release": "patch"
+          },
+          {
+            "type": "deps",
+            "release": "patch"
+          },
+          {
+            "type": "security",
+            "release": "patch"
+          },
+          {
+            "type": "docs",
+            "release": false
+          },
+          {
+            "type": "test",
+            "release": false
+          },
+          {
+            "type": "chore",
+            "release": false
+          },
+          {
+            "type": "build",
+            "release": false
+          },
+          {
+            "type": "ci",
+            "release": false
+          },
+          {
+            "type": "style",
+            "release": false
+          }
+        ],
+        "parserOpts": {
+          "noteKeywords": [
+            "BREAKING CHANGE",
+            "BREAKING CHANGES"
+          ]
+        }
+      }
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        "preset": "conventionalcommits",
+        "presetConfig": {
+          "types": [
+            {
+              "type": "feat",
+              "section": "Features",
+              "hidden": false
+            },
+            {
+              "type": "fix",
+              "section": "Bug Fixes",
+              "hidden": false
+            },
+            {
+              "type": "perf",
+              "section": "Performance Improvements",
+              "hidden": false
+            },
+            {
+              "type": "refactor",
+              "section": "Refactoring",
+              "hidden": false
+            },
+            {
+              "type": "deps",
+              "section": "Dependency Updates",
+              "hidden": false
+            },
+            {
+              "type": "security",
+              "section": "Security Fixes",
+              "hidden": false
+            },
+            {
+              "type": "revert",
+              "section": "Reverts",
+              "hidden": false
+            }
+          ]
+        },
+        "parserOpts": {
+          "noteKeywords": [
+            "BREAKING CHANGE",
+            "BREAKING CHANGES"
+          ]
+        }
+      }
+    ]
+  ]
+}

AGENTS.md

@@ -10,6 +10,126 @@ All AI agents and contributors must follow these rules when writing, reviewing,
 - Use `@.ai/environment/tools.raw.yaml` only when you need the full collected facts behind the AI-facing hints.
 - Prefer the project-relevant tools listed there instead of assuming every installed system tool is fair game.
 - If the real environment differs from the inventory, use the project-relevant installed tool and report the mismatch.
+- When working in WSL against this repository's Windows-backed worktree, first prefer Linux `git` with an explicit
+  `--git-dir=<repo>/.git/worktrees/<worktree-name>` and `--work-tree=<worktree-root>` binding for every repository
+  command. Treat that explicit binding as higher priority than `git.exe`, because it avoids WSL worktree path
+  translation mistakes and still works in sessions where Windows `.exe` execution is unavailable.
+- If a plain Linux `git` command in WSL fails with a worktree-style “not a git repository” path translation error,
+  rerun it with the explicit `--git-dir` / `--work-tree` binding before trying `git.exe`.
+- Only prefer Windows Git from WSL (for example `git.exe`) when that executable is both resolvable and executable in the
+  current session, and when the explicit Linux `git` binding is unavailable or has already failed.
+- If the shell resolves `git.exe` but the current WSL session cannot execute it cleanly (for example `Exec format
+  error`), keep using the explicit Linux `git` binding for the rest of the task instead of retrying Windows Git.
+- If the shell does not currently resolve `git.exe` to the host Windows Git installation and you still need Windows Git
+  as a fallback, prepend that installation's command directory to `PATH` and reset shell command hashing for the
+  current session before continuing.
+- After resolving either strategy, prefer a session-local binding or command wrapper for subsequent Git commands so the
+  shell does not silently fall back to the wrong repository context later in the same WSL session.
+
+## Git Workflow Rules
+
+- Every completed task MUST pass at least one build validation before it is considered done.
+- When the goal is to inspect or reduce warnings printed during project build, contributors MUST establish the warning
+  baseline from a non-incremental repository-root build by running `dotnet clean` and then `dotnet build`.
+- Contributors MUST NOT treat a repeated incremental `dotnet build` result as authoritative for warning inspection when
+  a clean baseline has not been captured in the same round.
+- If a direct `dotnet clean`, `dotnet build`, or `dotnet test` command fails inside the agent sandbox with missing
+  diagnostics, `Permission denied`, MSBuild pipe/socket errors, or other environment-only noise that does not match a
+  normal shell invocation, contributors MUST request permission and rerun the same direct command outside the sandbox
+  before concluding that the repository or toolchain is broken.
+- For repository truth, contributors MUST prefer the result of the original direct command executed outside the sandbox
+  over sandbox-only failures, workaround-heavy variants, or speculative environment flags unless the user explicitly
+  asks for a non-default command shape.
+- If the task changes multiple projects or shared abstractions, prefer a solution-level or affected-project
+  `dotnet build ... -c Release`; otherwise use the smallest build command that still proves the result compiles.
+- When a task adds a feature or modifies code, contributors MUST run a Release build for every directly affected
+  module/project instead of relying on an unrelated project or solution slice that does not actually compile the touched
+  code.
+- Warnings reported by those affected-module builds are part of the task scope. Contributors MUST resolve the touched
+  module's build warnings in the same change, or stop and explicitly report the exact warning IDs and blocker instead of
+  deferring them to a separate long-lived cleanup branch by default.
+- If the required build passes and there are task-related staged or unstaged changes, contributors MUST create a Git
+  commit automatically instead of leaving the task uncommitted, unless the user explicitly says not to commit.
+- Commit messages MUST use Conventional Commits format: `<type>(<scope>): <summary>`.
+- The commit `summary` MUST use simplified Chinese and briefly describe the main change.
+- The commit `body` MUST use unordered list items, and each item MUST start with a verb such as `新增`、`修复`、`优化`、
+  `更新`、`补充`、`重构`.
+- Each commit body bullet MUST describe one independent change point; avoid repeated or redundant descriptions.
+- Commit `type` MUST reflect release semantics instead of author intent:
+  - Use `feat` only for user-facing or consumer-facing capability additions that should raise the next released version's
+    `minor` segment.
+  - Use `fix` for behavior corrections, `perf` for observable performance improvements, and `refactor` only for
+    non-feature code restructuring; these should raise the next released version's `patch` segment.
+  - Use `deps` for dependency version updates, dependency lockfile refreshes, and package maintenance that should raise
+    the next released version's `patch` segment.
+  - Use `security` for vulnerability fixes, dependency security mitigations, and security configuration corrections
+    that should raise the next released version's `patch` segment.
+  - Use `docs`、`test`、`chore`、`build`、`ci`、`style` for their literal categories; do not encode these changes as
+    `feat` just because they feel important. These categories MUST NOT trigger a release.
+  - Use `BREAKING CHANGE` in the commit footer or `!` after the type / scope header (for example `feat!:` or
+    `feat(core)!:`) when the change should raise the next released version's `major` segment.
+- Documentation-only changes MUST NOT use `feat`, including new guides, refreshed examples, navigation updates, and
+  adoption notes for existing capabilities. If a commit changes both product behavior and related docs, either split the
+  commit or use `feat` only when the code/package behavior is the primary released change.
+- Contributors MUST avoid ambiguous scopes such as `feat(docs)` for documentation work. If the change only affects docs,
+  prefer `docs(<module-or-area>)`; if it adds a real capability in a docs-related toolchain, use the scope of that
+  actual subsystem instead of `docs`.
+- Keep technical terms in English when they are established project terms, such as `API`、`Model`、`System`.
+- When composing a multi-line commit body from shell commands, contributors MUST NOT rely on Bash `$"..."` quoting for
+  newline escapes, because it passes literal `\n` sequences to Git. Use multiple `-m` flags or ANSI-C `$'...'`
+  quoting so the commit body contains real line breaks.
+- If a new task starts while the current branch is `main`, contributors MUST first try to update local `main` from the
+  remote, then create and switch to a dedicated branch before making substantive changes.
+- The branch naming rule for a new task branch is `<type>/<topic-or-scope>`, where `<type>` should match the intended
+  Conventional Commit category as closely as practical.
+
+## License Header Rules
+
+- Repository-maintained source and configuration files that are supported by `scripts/license-header.py` MUST include an
+  Apache-2.0 file header before the task is considered complete.
+- When creating or modifying supported files, contributors MUST preserve an existing compliant header or add the SPDX
+  header generated by `python3 scripts/license-header.py --fix`.
+- Before committing changes that add or modify supported source/configuration files, contributors MUST run
+  `python3 scripts/license-header.py --check` and resolve any missing or misplaced headers.
+- For files with shebang lines, keep the shebang as the first line and place the license header immediately after it.
+- For XML/MSBuild files with an XML declaration, keep the XML declaration as the first node and place the license header
+  immediately after it.
+- Do not add project license headers to excluded or third-party areas such as `.agents/**`, `ai-libs/**`,
+  `third-party-licenses/**`, generated snapshots, binary assets, lock files, and generated build output. Treat
+  `scripts/license-header.py` as the authoritative include/exclude policy for this check.
+- If CI reports a license-header failure, either fix it locally with `python3 scripts/license-header.py --fix` or, for
+  maintainer-owned cleanup, use the manual `License Header Fix` GitHub Actions workflow to create a reviewed repair PR.
+
+## Repository Boot Skill
+
+- The repository-maintained Codex boot skill lives at `.codex/skills/gframework-boot/`.
+- Prefer invoking `$gframework-boot` when the user uses short startup prompts such as `boot`、`continue`、`next step`、
+  `按 boot 开始`、`先看 AGENTS`、`继续当前任务`.
+- The boot skill is a startup convenience layer, not a replacement for this document. If the skill and `AGENTS.md`
+  diverge, follow `AGENTS.md` first and update the skill in the same change.
+- The boot skill MUST read `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md` and the relevant
+  active-topic `ai-plan/` artifacts before substantive execution.
+
+## Subagent Usage Rules
+
+- Use subagents only when the task is complex, the context is likely to grow too large, or the work can be split into
+  independent parallel subtasks.
+- The main agent MUST identify the critical path first. Do not delegate the immediate blocking task if the next local
+  step depends on that result.
+- Use `explorer` subagents for read-only discovery, comparison, tracing, and narrow codebase questions.
+- Use `worker` subagents only for bounded implementation tasks with an explicit file or module ownership boundary.
+- Every delegation MUST specify:
+    - the concrete objective
+    - the expected output format
+    - the files or subsystem the subagent owns
+    - any constraints about tests, diagnostics, or compatibility
+- Subagents are not allowed to revert or overwrite unrelated changes from the user or other agents. They must adapt to
+  concurrent work instead of assuming exclusive ownership of the repository.
+- Prefer lightweight models such as `gpt-5.1-codex-mini` for narrow exploration, indexing, and comparison tasks.
+- Prefer stronger models such as `gpt-5.4` for cross-module design work, non-trivial refactors, and tasks that require
+  higher confidence reasoning.
+- The main agent remains responsible for reviewing and integrating subagent output. Unreviewed subagent conclusions do
+  not count as final results.
 
 ## Commenting Rules (MUST)
 
@@ -92,6 +212,9 @@ All generated or modified code MUST include clear and meaningful comments where
   - Private fields: `_camelCase`
 - Keep abstractions projects free of implementation details and engine-specific dependencies.
 - Preserve existing module boundaries. Do not introduce new cross-module dependencies without clear architectural need.
+- Framework runtime, abstractions, and meta-package projects MUST NOT reference `*.SourceGenerators*` projects or packages,
+  and MUST NOT use source-generator attributes such as `GenerateEnumExtensions` or `ContextAware`. Those capabilities are
+  reserved for consumer projects, generator projects, examples explicitly meant to demonstrate generator usage, and related tests.
 
 ### Formatting
 
@@ -100,6 +223,10 @@ All generated or modified code MUST include clear and meaningful comments where
 - Keep `using` directives at the top of the file and sort them consistently.
 - Separate logical blocks with blank lines when it improves readability.
 - Prefer one primary type per file unless the surrounding project already uses a different local pattern.
+- Unless there is a clear and documented reason to keep a file large, keep a single source file under roughly 800-1000
+  lines.
+- If a file grows beyond that range, contributors MUST stop and check whether responsibilities should be split before
+  continuing; treating oversized files as the default is considered a design smell.
 - Keep line length readable. Around 120 characters is the preferred upper bound.
 
 ### C# Conventions
@@ -114,6 +241,15 @@ All generated or modified code MUST include clear and meaningful comments where
 ### Analyzer and Validation Expectations
 
 - The repository uses `Meziantou.Analyzer`; treat analyzer feedback as part of the coding standard.
+- Treat SonarQube maintainability rules as part of the coding standard as well, especially cognitive complexity and
+  oversized parameter list findings.
+- When a method approaches analyzer complexity limits, prefer extracting named helper methods by semantic phase
+  (parsing, normalization, validation, diagnostics) instead of silencing the warning or doing cosmetic reshuffles.
+- When a constructor or method exceeds parameter count limits, choose the refactor that matches the shape of the API:
+  use domain-specific value objects or parameter objects for naturally grouped data, and prefer named factory methods
+  when the call site is really selecting between different creation modes.
+- Do not add suppressions for complexity or parameter-count findings unless the constraint is externally imposed and the
+  reason is documented in code comments.
 - Naming must remain compatible with `scripts/validate-csharp-naming.sh`.
 
 ## Testing Requirements
@@ -123,6 +259,8 @@ All generated or modified code MUST include clear and meaningful comments where
 - Every non-trivial feature, bug fix, or behavior change MUST include tests or an explicit justification for why a test
   is not practical.
 - Public API changes must be covered by unit or integration tests.
+- When a public API defines multiple contract branches, tests MUST cover the meaningful variants, including null,
+  empty, default, and filtered inputs when those branches change behavior.
 - Regression fixes should include a test that fails before the fix and passes after it.
 
 ### Test Organization
@@ -143,8 +281,14 @@ All generated or modified code MUST include clear and meaningful comments where
 ### Validation Commands
 
 Use the smallest command set that proves the change, then expand if the change is cross-cutting.
+If a sandboxed agent run reports environment-specific .NET failures, rerun the same direct command outside the sandbox
+and treat that unsandboxed result as authoritative for validation and warning baselines.
 
 ```bash
+# Check warnings from the default repository build entrypoint
+dotnet clean
+dotnet build
+
 # Build the full solution
 dotnet build GFramework.sln -c Release
 
@@ -193,13 +337,137 @@ bash scripts/validate-csharp-naming.sh
 - If a framework abstraction changes meaning or intended usage, update the explanatory comments in code as part of the
   same change.
 
+### Documentation Source Of Truth
+
+- Treat source code, `*.csproj`, tests, generated snapshots, and packaging metadata as the primary evidence for
+  documentation updates.
+- Treat verified reference implementations under `ai-libs/` as a secondary evidence source for real project adoption
+  patterns, directory layouts, and end-to-end usage examples.
+- Treat existing `README.md` files and `docs/zh-CN/` pages as editable outputs, not authoritative truth.
+- If existing documentation conflicts with code or tests, update the documentation to match the implementation instead
+  of preserving outdated wording.
+- Do not publish example code, setup steps, or package guidance that cannot be traced back to code, tests, or a
+  verified consumer project.
+
+### Module README Requirements
+
+- Every user-facing package or module directory that contains a `*.csproj` intended for direct consumption MUST have a
+  sibling `README.md`.
+- Use the canonical filename `README.md`. Do not introduce new `ReadMe.md` or other filename variants.
+- A module README MUST describe:
+  - the module's purpose
+  - the relationship to adjacent runtime, abstractions, or generator packages
+  - the major subdirectories or subsystems the reader is expected to use
+  - the minimum adoption path
+  - the corresponding `docs/zh-CN/` entry points
+- Adding a new top-level module directory without a `README.md` is considered incomplete work.
+- If a module's responsibilities, setup, public API surface, generator inputs, or adoption path change, update that
+  module's `README.md` in the same change.
+
 ### Repository Documentation
 
 - Update the relevant `README.md` or `docs/` page when behavior, setup steps, architecture guidance, or user-facing
   examples change.
+- Public documentation under `README.md` and `docs/**` MUST stay reader-facing. Do not publish governance-only content
+  such as inventory tables, coverage baselines, review queues, batch metrics, recovery points, trace summaries, or
+  “this still needs a later audit wave” notes in those user-facing pages.
+- Public documentation MUST use semantic section titles and link labels. Do not surface raw filenames or paths such as
+  `README.md`、`game/index.md`、`../core/cqrs.md` as reader-facing navigation text when a meaningful destination label is
+  available.
+- Public documentation MUST avoid rhetorical, self-referential, or AI-sounding headings and prompts such as
+  “你真正会用到的公开入口”、
+  “先理解包关系”、
+  “这个栏目应该回答什么” or “想看……转到……”. Prefer neutral labels such as
+  “公开入口”、
+  “模块与包关系”、
+  “栏目覆盖范围” and “相关主题”.
+- Public documentation MUST present limitations, suitability, and migration boundaries as adoption guidance for readers.
+  Do not publish internal-governance or product-roadmap wording such as “当前阶段的结论”、
+  “不建议立即启动”、
+  “仓库当前的主要使用者” or similar maintainer-facing decision records in `README.md` or `docs/**`; that material
+  belongs in `ai-plan/**` if it must be tracked.
+- Governance-only material such as XML audit snapshots, documentation remediation baselines, backlog status, and
+  recovery metadata belongs in `ai-plan/**` or other contributor-only artifacts, not in public docs.
+- Treat `ai-libs/` as a read-only third-party source reference area.
+- Code under `ai-libs/**` exists for comparison, tracing, design study, and behavior verification; do not modify it
+  unless the user explicitly asks to sync or update that third-party snapshot.
+- When implementation plans, traces, reviews, or design notes say “reference a third-party project”, prefer the
+  repository-local path under `ai-libs/` instead of an unspecified upstream repository.
+- If a task depends on observations from `ai-libs/**`, record the referenced path and conclusion in the active plan or
+  trace when the work is multi-step or complex, or when an active tracking document already exists, rather than editing
+  the third-party reference copy.
 - The main documentation site lives under `docs/`, with Chinese content under `docs/zh-CN/`.
 - Keep code samples, package names, and command examples aligned with the current repository state.
 - Prefer documenting behavior and design intent, not only API surface.
+- When a public page references XML docs or API coverage, convert that evidence into reader-facing guidance: explain
+  which types, namespaces, or entry points readers should inspect and why, instead of exposing audit counts or
+  governance terminology.
+- When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the
+  corresponding user-facing integration documentation in `docs/zh-CN/` in the same change.
+- For integration-oriented features such as the AI-First config system, documentation MUST cover:
+    - project directory layout and file conventions
+    - required project or package wiring
+    - minimal working usage example
+    - migration or compatibility notes when behavior changes
+- If an existing documentation page no longer reflects the current implementation, fixing the code without fixing the
+  documentation is considered incomplete work.
+- Do not rely on “the code is self-explanatory” for framework features that consumers need to adopt; write the
+  adoption path down so future users do not need to rediscover it from source.
+- The repository root `README.md` MUST mirror the current top-level documentation taxonomy used by the docs site.
+  Do not maintain a second, differently named navigation system in the root README.
+- Prefer linking the root `README.md` to section landing pages such as `index.md` instead of deep-linking to a single
+  article when the target is intended to be a documentation category.
+- If a docs category appears in VitePress navigation or sidebar, it MUST have a real landing page or be removed from
+  navigation in the same change.
+- When examples are rewritten, preserve only the parts that remain true. Delete or replace speculative examples instead
+  of lightly editing them into another inaccurate form.
+
+### Task Tracking
+
+- `ai-plan/` is split by intent:
+  - `ai-plan/public/README.md`: the shared startup index that binds worktrees or branches to active topics and resume
+    entry points
+  - `ai-plan/public/<topic>/todos/`: repository-safe recovery documents for an active topic
+  - `ai-plan/public/<topic>/traces/`: repository-safe execution traces for an active topic
+  - `ai-plan/public/<topic>/archive/`: archived stage-level artifacts that still belong to an active topic; prefer
+    `archive/todos/` and `archive/traces/` when archiving content cut out of the active entry files
+  - `ai-plan/public/archive/<topic>/`: completed-topic archives that should not be treated as default boot context
+  - `ai-plan/private/`: worktree-private recovery artifacts; keep these untracked and scoped to the current worktree
+- Contributors MUST keep committed `ai-plan/public/**` content safe to publish in Git history.
+- Never write secrets, tokens, credentials, private keys, machine usernames, home-directory paths, hostnames, IP
+  addresses, proprietary URLs, or other sensitive environment details into any `ai-plan/**` file.
+- Never record absolute file-system paths in `ai-plan/**`; use repository-relative paths, branch names, PR numbers, or
+  stable document identifiers instead.
+- Use `ai-plan/public/**` only for durable, handoff-safe task state. Put temporary notes, local experiments, or
+  worktree-specific scratch recovery data under `ai-plan/private/`.
+- `ai-plan/public/README.md` MUST list only active topics. Do not add `ai-plan/public/archive/**` content to the
+  default boot index.
+- When a worktree-to-topic mapping changes, or when a topic becomes active/inactive, contributors MUST update
+  `ai-plan/public/README.md` in the same change.
+- When working from a tracked implementation plan, contributors MUST update the corresponding tracking document under
+  `ai-plan/public/<topic>/todos/` in the same change.
+- Tracking updates MUST reflect completed work, newly discovered issues, validation results, and the next recommended
+  recovery point.
+- Active tracking and trace files are recovery entrypoints, not append-only changelogs. They MUST stay concise enough
+  for `boot` to locate the current recovery point quickly.
+- Completing code changes without updating the active tracking document is considered incomplete work.
+- For any multi-step refactor, migration, or cross-module task, contributors MUST create or adopt a dedicated recovery
+  document under `ai-plan/public/<topic>/todos/` before making substantive code changes.
+- Recovery documents MUST record the current phase, the active recovery point identifier, known risks, and the next
+  recommended resume step so another contributor or subagent can continue the work safely.
+- Contributors MUST maintain a matching execution trace under `ai-plan/public/<topic>/traces/` for complex work. The
+  trace should record the current date, key decisions, validation milestones, and the immediate next step.
+- When a stage inside an active topic is fully complete, move the finished artifacts into that topic's `archive/`
+  directory instead of leaving every completed step in the default boot path.
+- When completed and validated stages begin to accumulate, contributors MUST archive their detailed history out of the
+  active `todos/` and `traces/` entry files in the same change. Keep only the current recovery point, active facts,
+  active risks, immediate next step, and pointers to the relevant archive files in the default boot path.
+- When a topic is fully complete, move the entire topic directory under `ai-plan/public/archive/<topic>/` and remove it
+  from `ai-plan/public/README.md` in the same change.
+- When a task spans multiple commits or is likely to exceed a single agent context window, update both the recovery
+  document and the trace at each meaningful milestone before pausing or handing work off.
+- If subagents are used on a complex task, the main agent MUST capture the delegated scope and any accepted findings in
+  the active recovery document or trace before continuing implementation.
 
 ### Documentation Preview
 
@@ -218,3 +486,4 @@ Before considering work complete, confirm:
 - Relevant tests were added or updated
 - Sensitive or unsafe behavior was not introduced
 - User-facing documentation is updated when needed
+- Feature adoption docs under `docs/zh-CN/` were added or updated when functionality was added, removed, or refactored

CLAUDE.md

@@ -18,17 +18,22 @@ Follow them strictly.
 
 ```text
 GFramework (meta package) ─→ Core + Game
+GFramework.Cqrs ─→ Cqrs.Abstractions, Core.Abstractions
 GFramework.Core ─→ Core.Abstractions
 GFramework.Game ─→ Game.Abstractions, Core, Core.Abstractions
 GFramework.Godot ─→ Core, Game, Core.Abstractions, Game.Abstractions
 GFramework.Ecs.Arch ─→ Ecs.Arch.Abstractions, Core, Core.Abstractions
-GFramework.SourceGenerators ─→ SourceGenerators.Common, SourceGenerators.Abstractions
+GFramework.Core.SourceGenerators ─→ Core.SourceGenerators.Abstractions, SourceGenerators.Common
+GFramework.Game.SourceGenerators ─→ SourceGenerators.Common
+GFramework.Godot.SourceGenerators ─→ Godot.SourceGenerators.Abstractions, SourceGenerators.Common
+GFramework.Cqrs.SourceGenerators ─→ SourceGenerators.Common
 ```
 
 - **Abstractions projects** (`netstandard2.1`): 只包含接口和契约定义，不承载运行时实现逻辑。
 - **Core / Game / Ecs.Arch** (`net8.0;net9.0;net10.0`): 平台无关的核心实现层。
 - **Godot**: Godot 引擎集成层，负责与节点、场景和引擎生命周期对接。
-- **SourceGenerators** (`netstandard2.1`): Roslyn 增量源码生成器及其公共基础设施。
+- **SourceGenerators family** (`netstandard2.0`/`netstandard2.1`): 按 Core / Game / Godot / Cqrs 拆分的 Roslyn
+  增量源码生成器，以及共享的 abstractions/common 基础设施。
 
 ## Architecture Pattern
 
@@ -73,7 +78,8 @@ Architecture 负责统一生命周期编排，核心阶段包括：
 
 ### CQRS
 
-命令与查询分离，支持同步与异步执行。Mediator 模式通过源码生成器集成，以减少模板代码并保持调用路径清晰。
+命令与查询分离，支持同步与异步执行。当前版本内建自有 CQRS runtime、行为管道和 handler 自动注册；历史 `Mediator`
+兼容别名已从公开 API 移除，统一使用 `Cqrs` 命名入口。
 
 ### EventBus
 
@@ -103,6 +109,8 @@ Architecture 负责统一生命周期编排，核心阶段包括：
 - `PriorityGenerator` (`[Priority]`): 生成优先级比较相关实现。
 - `EnumExtensionsGenerator` (`[GenerateEnumExtensions]`): 生成枚举扩展能力。
 - `ContextAwareGenerator` (`[ContextAware]`): 自动实现 `IContextAware` 相关样板逻辑。
+- `CqrsHandlerRegistryGenerator`: 为消费端程序集生成 CQRS handler 注册器，运行时优先使用生成产物，无法覆盖时回退到反射扫描；非默认程序集可通过
+  `RegisterCqrsHandlersFromAssembly(...)` / `RegisterCqrsHandlersFromAssemblies(...)` 显式接入同一路径。
 
 这些生成器的目标是减少重复代码，同时保持框架层 API 的一致性与可维护性。
 
@@ -111,10 +119,12 @@ Architecture 负责统一生命周期编排，核心阶段包括：
 仓库以“抽象层 + 实现层 + 集成层 + 生成器层”的方式组织：
 
 - `GFramework.Core.Abstractions` / `GFramework.Game.Abstractions`: 约束接口和公共契约。
+- `GFramework.Cqrs.Abstractions` / `GFramework.Cqrs`: 提供 CQRS 契约、runtime 与 handler 注册基础设施。
 - `GFramework.Core` / `GFramework.Game`: 提供平台无关实现。
 - `GFramework.Godot`: 提供与 Godot 运行时集成的适配实现。
 - `GFramework.Ecs.Arch`: 提供 ECS Architecture 相关扩展。
-- `GFramework.SourceGenerators` 及相关 Abstractions/Common: 提供代码生成能力。
+- `GFramework.Core.SourceGenerators` / `GFramework.Game.SourceGenerators` / `GFramework.Godot.SourceGenerators` /
+  `GFramework.Cqrs.SourceGenerators` 与相关 Abstractions/Common: 提供代码生成能力。
 
 这种结构的核心设计目标是让抽象稳定、实现可替换、引擎集成隔离、生成器能力可独立演进。
 

Directory.Build.props

@@ -0,0 +1,18 @@
+<!--
+  Copyright (c) 2025-2026 GeWuYou
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+<Project>
+    <!-- Keep repository-wide analyzer behavior consistent while allowing only selected projects to opt into polyfills. -->
+    <ItemGroup>
+        <PackageReference Include="Meziantou.Analyzer" Version="3.0.60">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
+        </PackageReference>
+        <PackageReference Update="Meziantou.Polyfill" Version="1.0.121">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
+        </PackageReference>
+    </ItemGroup>
+</Project>

Directory.Build.targets

@@ -1,3 +1,8 @@
+<!--
+  Copyright (c) 2025-2026 GeWuYou
+  SPDX-License-Identifier: Apache-2.0
+-->
+
 <Project>
 
     <!--

GFramework.Core.Abstractions/Architectures/ArchitectureModuleRegistry.cs

@@ -1,3 +1,6 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
 using System.Collections.Concurrent;
 
 namespace GFramework.Core.Abstractions.Architectures;

GFramework.Core.Abstractions/Architectures/ArchitecturePhaseChangedEventArgs.cs

@@ -0,0 +1,27 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using GFramework.Core.Abstractions.Enums;
+
+namespace GFramework.Core.Abstractions.Architectures;
+
+/// <summary>
+///     表示架构阶段变化事件的数据。
+///     该类型用于向事件订阅者传递当前已进入的阶段值。
+/// </summary>
+public sealed class ArchitecturePhaseChangedEventArgs : EventArgs
+{
+    /// <summary>
+    ///     初始化 <see cref="ArchitecturePhaseChangedEventArgs" /> 的新实例。
+    /// </summary>
+    /// <param name="phase">当前已进入的架构阶段。</param>
+    public ArchitecturePhaseChangedEventArgs(ArchitecturePhase phase)
+    {
+        Phase = phase;
+    }
+
+    /// <summary>
+    ///     获取当前已进入的架构阶段。
+    /// </summary>
+    public ArchitecturePhase Phase { get; }
+}

GFramework.Core.Abstractions/Architectures/IArchitecture.cs

@@ -1,8 +1,11 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using System.Reflection;
 using GFramework.Core.Abstractions.Lifecycle;
 using GFramework.Core.Abstractions.Model;
 using GFramework.Core.Abstractions.Systems;
 using GFramework.Core.Abstractions.Utility;
-using Microsoft.Extensions.DependencyInjection;
 
 namespace GFramework.Core.Abstractions.Architectures;
 
@@ -73,13 +76,32 @@ public interface IArchitecture : IAsyncInitializable, IAsyncDestroyable, IInitia
     void RegisterUtility<T>(Action<T>? onCreated = null) where T : class, IUtility;
 
     /// <summary>
-    ///     注册中介行为管道
-    ///     用于配置Mediator框架的行为拦截和处理逻辑
+    ///     注册 CQRS 请求管道行为。
+    ///     既支持实现 <c>IPipelineBehavior&lt;,&gt;</c> 的开放泛型行为类型，
+    ///     也支持绑定到单一请求/响应对的封闭行为类型。
     /// </summary>
     /// <typeparam name="TBehavior">行为类型，必须是引用类型</typeparam>
-    void RegisterMediatorBehavior<TBehavior>()
+    void RegisterCqrsPipelineBehavior<TBehavior>()
         where TBehavior : class;
 
+    /// <summary>
+    ///     从指定程序集显式注册 CQRS 处理器。
+    ///     当处理器位于默认架构程序集之外的模块或扩展程序集中时，可在初始化阶段调用该入口接入对应程序集。
+    /// </summary>
+    /// <param name="assembly">包含 CQRS 处理器或生成注册器的程序集。</param>
+    /// <exception cref="ArgumentNullException"><paramref name="assembly" /> 为 <see langword="null" />。</exception>
+    /// <exception cref="InvalidOperationException">当前架构的底层容器已冻结，无法继续注册处理器。</exception>
+    void RegisterCqrsHandlersFromAssembly(Assembly assembly);
+
+    /// <summary>
+    ///     从多个程序集显式注册 CQRS 处理器。
+    ///     该入口会对程序集集合去重，适用于统一接入多个扩展包或模块程序集。
+    /// </summary>
+    /// <param name="assemblies">要接入的程序集集合。</param>
+    /// <exception cref="ArgumentNullException"><paramref name="assemblies" /> 为 <see langword="null" />。</exception>
+    /// <exception cref="InvalidOperationException">当前架构的底层容器已冻结，无法继续注册处理器。</exception>
+    void RegisterCqrsHandlersFromAssemblies(IEnumerable<Assembly> assemblies);
+
     /// <summary>
     ///     安装架构模块
     /// </summary>
@@ -99,4 +121,4 @@ public interface IArchitecture : IAsyncInitializable, IAsyncDestroyable, IInitia
     /// </summary>
     /// <returns>表示异步等待操作的任务</returns>
     Task WaitUntilReadyAsync();
-}
+}

GFramework.Core.Abstractions/Architectures/IArchitectureConfiguration.cs

@@ -1,4 +1,7 @@
-using GFramework.Core.Abstractions.Properties;
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using GFramework.Core.Abstractions.Properties;
 
 namespace GFramework.Core.Abstractions.Architectures;
 

GFramework.Core.Abstractions/Architectures/IArchitectureContext.cs

@@ -1,3 +1,6 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
 using GFramework.Core.Abstractions.Command;
 using GFramework.Core.Abstractions.Environment;
 using GFramework.Core.Abstractions.Events;
@@ -5,15 +8,20 @@ using GFramework.Core.Abstractions.Model;
 using GFramework.Core.Abstractions.Query;
 using GFramework.Core.Abstractions.Systems;
 using GFramework.Core.Abstractions.Utility;
-using Mediator;
+using GFramework.Cqrs.Abstractions.Cqrs;
 using ICommand = GFramework.Core.Abstractions.Command.ICommand;
 
 namespace GFramework.Core.Abstractions.Architectures;
 
 /// <summary>
-///     架构上下文接口，提供对系统、模型、工具类的访问以及命令、查询、事件的发送和注册功能
+///     架构上下文接口，统一暴露框架组件访问、兼容旧命令/查询总线，以及当前推荐的 CQRS 运行时入口。
 /// </summary>
-public interface IArchitectureContext
+/// <remarks>
+///     <para>旧的 <c>GFramework.Core.Abstractions.Command</c> 与 <c>GFramework.Core.Abstractions.Query</c> 契约会继续通过原有 Command/Query Executor 路径执行，以保证存量代码兼容。</para>
+///     <para>新的 <c>GFramework.Cqrs.Abstractions.Cqrs</c> 契约由内置 CQRS dispatcher 统一处理，支持 request pipeline、notification publish 与 stream request。</para>
+///     <para>新功能优先使用 <see cref="SendRequestAsync{TResponse}(IRequest{TResponse},CancellationToken)" />、<see cref="SendAsync{TCommand}(TCommand,CancellationToken)" /> 与对应的 CQRS Command/Query 重载；迁移旧代码时可先保留旧入口，再逐步替换为 CQRS 请求模型。</para>
+/// </remarks>
+public interface IArchitectureContext : ICqrsContext
 {
     /// <summary>
     ///     获取指定类型的服务实例
@@ -104,87 +112,92 @@ public interface IArchitectureContext
     IReadOnlyList<TUtility> GetUtilitiesByPriority<TUtility>() where TUtility : class, IUtility;
 
     /// <summary>
-    ///     发送一个命令
+    ///     发送一个旧版命令。
     /// </summary>
-    /// <param name="command">要发送的命令</param>
+    /// <param name="command">要发送的旧版命令。</param>
     void SendCommand(ICommand command);
 
     /// <summary>
-    ///     发送一个带返回值的命令
+    ///     发送一个旧版带返回值命令。
     /// </summary>
-    /// <typeparam name="TResult">命令执行结果类型</typeparam>
-    /// <param name="command">要发送的命令</param>
-    /// <returns>命令执行结果</returns>
-    TResult SendCommand<TResult>(Command.ICommand<TResult> command);
+    /// <typeparam name="TResult">命令执行结果类型。</typeparam>
+    /// <param name="command">要发送的旧版命令。</param>
+    /// <returns>命令执行结果。</returns>
+    TResult SendCommand<TResult>(ICommand<TResult> command);
 
     /// <summary>
-    /// [Mediator] 发送命令的同步版本（不推荐，仅用于兼容性）
+    ///     发送一个新版 CQRS 命令并返回结果。
     /// </summary>
-    /// <typeparam name="TResponse">命令响应类型</typeparam>
-    /// <param name="command">要发送的命令对象</param>
-    /// <returns>命令执行结果</returns>
-    TResponse SendCommand<TResponse>(Mediator.ICommand<TResponse> command);
+    /// <typeparam name="TResponse">命令响应类型。</typeparam>
+    /// <param name="command">要发送的 CQRS 命令。</param>
+    /// <returns>命令执行结果。</returns>
+    /// <remarks>
+    ///     这是迁移后的推荐命令入口。无返回值命令应实现 <c>IRequest&lt;Unit&gt;</c>，并优先通过 <see cref="SendAsync{TCommand}(TCommand,CancellationToken)" /> 调用。
+    /// </remarks>
+    TResponse SendCommand<TResponse>(GFramework.Cqrs.Abstractions.Cqrs.Command.ICommand<TResponse> command);
 
 
     /// <summary>
-    ///     发送并异步执行一个命令
+    ///     异步发送一个旧版命令。
     /// </summary>
-    /// <param name="command">要发送的命令</param>
+    /// <param name="command">要发送的旧版命令。</param>
     Task SendCommandAsync(IAsyncCommand command);
 
     /// <summary>
-    /// [Mediator] 异步发送命令并返回结果
-    /// 通过Mediator模式发送命令请求，支持取消操作
+    ///     异步发送一个新版 CQRS 命令并返回结果。
     /// </summary>
-    /// <typeparam name="TResponse">命令响应类型</typeparam>
-    /// <param name="command">要发送的命令对象</param>
-    /// <param name="cancellationToken">取消令牌，用于取消操作</param>
-    /// <returns>包含命令执行结果的ValueTask</returns>
-    ValueTask<TResponse> SendCommandAsync<TResponse>(Mediator.ICommand<TResponse> command,
+    /// <typeparam name="TResponse">命令响应类型。</typeparam>
+    /// <param name="command">要发送的 CQRS 命令。</param>
+    /// <param name="cancellationToken">取消令牌。</param>
+    /// <returns>包含命令执行结果的值任务。</returns>
+    ValueTask<TResponse> SendCommandAsync<TResponse>(
+        GFramework.Cqrs.Abstractions.Cqrs.Command.ICommand<TResponse> command,
         CancellationToken cancellationToken = default);
 
 
     /// <summary>
-    ///     发送并异步执行一个带返回值的命令
+    ///     异步发送一个旧版带返回值命令。
     /// </summary>
-    /// <typeparam name="TResult">命令执行结果类型</typeparam>
-    /// <param name="command">要发送的命令</param>
-    /// <returns>命令执行结果</returns>
+    /// <typeparam name="TResult">命令执行结果类型。</typeparam>
+    /// <param name="command">要发送的旧版命令。</param>
+    /// <returns>命令执行结果。</returns>
     Task<TResult> SendCommandAsync<TResult>(IAsyncCommand<TResult> command);
 
     /// <summary>
-    ///     发送一个查询请求
+    ///     发送一个旧版查询请求。
     /// </summary>
-    /// <typeparam name="TResult">查询结果类型</typeparam>
-    /// <param name="query">要发送的查询</param>
-    /// <returns>查询结果</returns>
-    TResult SendQuery<TResult>(Query.IQuery<TResult> query);
+    /// <typeparam name="TResult">查询结果类型。</typeparam>
+    /// <param name="query">要发送的旧版查询。</param>
+    /// <returns>查询结果。</returns>
+    TResult SendQuery<TResult>(IQuery<TResult> query);
 
     /// <summary>
-    /// [Mediator] 发送查询的同步版本（不推荐，仅用于兼容性）
+    ///     发送一个新版 CQRS 查询并返回结果。
     /// </summary>
-    /// <typeparam name="TResponse">查询响应类型</typeparam>
-    /// <param name="query">要发送的查询对象</param>
-    /// <returns>查询结果</returns>
-    TResponse SendQuery<TResponse>(Mediator.IQuery<TResponse> query);
+    /// <typeparam name="TResponse">查询响应类型。</typeparam>
+    /// <param name="query">要发送的 CQRS 查询。</param>
+    /// <returns>查询结果。</returns>
+    /// <remarks>
+    ///     这是迁移后的推荐查询入口。新查询应优先实现 <c>GFramework.Cqrs.Abstractions.Cqrs.Query.IQuery&lt;TResponse&gt;</c>。
+    /// </remarks>
+    TResponse SendQuery<TResponse>(GFramework.Cqrs.Abstractions.Cqrs.Query.IQuery<TResponse> query);
 
     /// <summary>
-    ///     异步发送一个查询请求
+    ///     异步发送一个旧版查询请求。
     /// </summary>
-    /// <typeparam name="TResult">查询结果类型</typeparam>
-    /// <param name="query">要发送的异步查询</param>
-    /// <returns>查询结果</returns>
+    /// <typeparam name="TResult">查询结果类型。</typeparam>
+    /// <param name="query">要发送的旧版异步查询。</param>
+    /// <returns>查询结果。</returns>
     Task<TResult> SendQueryAsync<TResult>(IAsyncQuery<TResult> query);
 
     /// <summary>
-    /// [Mediator] 异步发送查询并返回结果
-    /// 通过Mediator模式发送查询请求，支持取消操作
+    ///     异步发送一个新版 CQRS 查询并返回结果。
     /// </summary>
-    /// <typeparam name="TResponse">查询响应类型</typeparam>
-    /// <param name="query">要发送的查询对象</param>
-    /// <param name="cancellationToken">取消令牌，用于取消操作</param>
-    /// <returns>包含查询结果的ValueTask</returns>
-    ValueTask<TResponse> SendQueryAsync<TResponse>(Mediator.IQuery<TResponse> query,
+    /// <typeparam name="TResponse">查询响应类型。</typeparam>
+    /// <param name="query">要发送的 CQRS 查询。</param>
+    /// <param name="cancellationToken">取消令牌。</param>
+    /// <returns>包含查询结果的值任务。</returns>
+    ValueTask<TResponse> SendQueryAsync<TResponse>(GFramework.Cqrs.Abstractions.Cqrs.Query.IQuery<TResponse> query,
         CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -216,28 +229,40 @@ public interface IArchitectureContext
     void UnRegisterEvent<TEvent>(Action<TEvent> onEvent);
 
     /// <summary>
-    /// 发送请求（统一处理 Command/Query）
+    /// 发送新版 CQRS 请求，并统一处理命令与查询。
     /// </summary>
+    /// <remarks>
+    /// 这是自有 CQRS 运行时的主入口。新代码应优先通过该方法或 <see cref="SendAsync{TCommand}(TCommand,CancellationToken)" /> 进入 dispatcher。
+    /// </remarks>
     ValueTask<TResponse> SendRequestAsync<TResponse>(
         IRequest<TResponse> request,
         CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// 发送请求（同步版本，不推荐）
+    /// 发送新版 CQRS 请求的同步包装版本。
     /// </summary>
+    /// <remarks>
+    /// 仅为兼容同步调用链保留；新代码应优先使用异步入口，避免阻塞当前线程。
+    /// </remarks>
     TResponse SendRequest<TResponse>(IRequest<TResponse> request);
 
     /// <summary>
-    /// 发布通知（一对多事件）
+    /// 发布新版 CQRS 通知。
     /// </summary>
+    /// <remarks>
+    /// 该入口用于一对多通知分发，与框架级 <c>EventBus</c> 事件系统并存，适合围绕请求处理过程传播领域通知。
+    /// </remarks>
     ValueTask PublishAsync<TNotification>(
         TNotification notification,
         CancellationToken cancellationToken = default)
         where TNotification : INotification;
 
     /// <summary>
-    /// 创建流式请求（用于大数据集）
+    /// 创建新版 CQRS 流式请求。
     /// </summary>
+    /// <remarks>
+    /// 适用于需要按序惰性产出大量结果的场景。调用方应消费返回的异步序列，而不是回退到旧版查询总线。
+    /// </remarks>
     IAsyncEnumerable<TResponse> CreateStream<TResponse>(
         IStreamRequest<TResponse> request,
         CancellationToken cancellationToken = default);
@@ -245,7 +270,7 @@ public interface IArchitectureContext
     // === 便捷扩展方法 ===
 
     /// <summary>
-    /// 发送命令（无返回值）
+    /// 发送一个无返回值的新版 CQRS 命令。
     /// </summary>
     ValueTask SendAsync<TCommand>(
         TCommand command,
@@ -253,7 +278,7 @@ public interface IArchitectureContext
         where TCommand : IRequest<Unit>;
 
     /// <summary>
-    /// 发送命令（有返回值）
+    /// 发送一个有返回值的新版 CQRS 请求。
     /// </summary>
     ValueTask<TResponse> SendAsync<TResponse>(
         IRequest<TResponse> command,
@@ -265,4 +290,4 @@ public interface IArchitectureContext
     /// </summary>
     /// <returns>环境对象实例</returns>
     IEnvironment GetEnvironment();
-}
+}

GFramework.Core.Abstractions/Architectures/IArchitectureContextProvider.cs

@@ -1,3 +1,6 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
 namespace GFramework.Core.Abstractions.Architectures;
 
 /// <summary>

GFramework.Core.Abstractions/Architectures/IArchitectureLifecycleHook.cs

@@ -1,4 +1,7 @@
-using GFramework.Core.Abstractions.Enums;
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using GFramework.Core.Abstractions.Enums;
 
 namespace GFramework.Core.Abstractions.Architectures;
 

GFramework.Core.Abstractions/Architectures/IArchitectureModule.cs

@@ -1,4 +1,7 @@
-namespace GFramework.Core.Abstractions.Architectures;
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+namespace GFramework.Core.Abstractions.Architectures;
 
 /// <summary>
 ///     架构模块接口，继承自架构生命周期接口。

GFramework.Core.Abstractions/Architectures/IArchitecturePhaseListener.cs

@@ -1,4 +1,7 @@
-using GFramework.Core.Abstractions.Enums;
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using GFramework.Core.Abstractions.Enums;
 
 namespace GFramework.Core.Abstractions.Architectures;
 

GFramework.Core.Abstractions/Architectures/IArchitectureServices.cs

@@ -1,3 +1,6 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
 using GFramework.Core.Abstractions.Command;
 using GFramework.Core.Abstractions.Events;
 using GFramework.Core.Abstractions.Ioc;

GFramework.Core.Abstractions/Architectures/IServiceModule.cs

@@ -1,3 +1,6 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
 using GFramework.Core.Abstractions.Ioc;
 using GFramework.Core.Abstractions.Lifecycle;
 

GFramework.Core.Abstractions/Architectures/IServiceModuleManager.cs

@@ -1,3 +1,6 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
 using GFramework.Core.Abstractions.Ioc;
 
 namespace GFramework.Core.Abstractions.Architectures;

GFramework.Core.Abstractions/Bases/IKeyValue.cs

@@ -1,4 +1,7 @@
-namespace GFramework.Core.Abstractions.Bases;
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+namespace GFramework.Core.Abstractions.Bases;
 
 /// <summary>
 ///     表示键值对的接口，定义了通用的键值对数据结构契约

GFramework.Core.Abstractions/Bases/IPrioritized.cs

@@ -1,3 +1,6 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
 namespace GFramework.Core.Abstractions.Bases;
 
 /// <summary>

GFramework.Core.Abstractions/Bases/PriorityGroup.cs

@@ -1,3 +1,6 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
 namespace GFramework.Core.Abstractions.Bases;
 
 /// <summary>

GFramework.Core.Abstractions/Command/IAsyncCommand.cs

@@ -1,3 +1,6 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
 using GFramework.Core.Abstractions.Rule;
 
 namespace GFramework.Core.Abstractions.Command;