GeWuYou · GeWuYou · Apr 19, 2026 · Apr 18, 2026 · Apr 18, 2026 · Apr 18, 2026
diff --git a/.codex b/.codex
diff --git a/.codex/skills/gframework-boot/SKILL.md b/.codex/skills/gframework-boot/SKILL.md
@@ -0,0 +1,61 @@
+---
+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 local-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. Inspect `local-plan/todos/` and `local-plan/traces/` before asking the user for missing context.
+4. 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
+5. Choose the best matching `local-plan` artifacts:
+   - 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
+6. 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
+7. 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
+8. Before editing files, tell the user what you read, how you classified the task, whether subagents will be used, and the first implementation step.
+9. 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 the active document under `local-plan/todos/` with completed work, validation results, risks, and the next recovery point.
+- Update the matching document under `local-plan/traces/` with key decisions, delegated scope, and the immediate next step.
+- 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, assume recovery mode and search `local-plan/` first.
+- If the current branch and the newest recovery documents describe the same feature area, prefer resuming that thread.
+- 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 local-plan, then start the next step`
+- `继续当前任务，先看 AGENTS.md 和 local-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.
diff --git a/.codex/skills/gframework-boot/agents/openai.yaml b/.codex/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."
diff --git a/.codex/skills/gframework-boot/references/startup-artifacts.md b/.codex/skills/gframework-boot/references/startup-artifacts.md
@@ -0,0 +1,31 @@
+# Startup Artifacts
+
+## Required Reads
+
+- `AGENTS.md`
+- `.ai/environment/tools.ai.yaml`
+- `local-plan/todos/`
+- `local-plan/traces/`
+
+## Local-Plan Selection Heuristics
+
+- Match the user's wording against todo and trace file names first.
+- 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.
+
+## 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, and the relevant local-plan artifacts. This looks like a <task-state> <complexity> task. I will <delegate-or-not> and start with <first-step>.`
diff --git a/.gitignore b/.gitignore
@@ -15,5 +15,6 @@ opencode.json
 docs/.omc/
 docs/.vitepress/cache/
 local-plan/
+ai-libs/
 # tool
 .venv/
diff --git a/AGENTS.md b/AGENTS.md
@@ -37,6 +37,16 @@ All AI agents and contributors must follow these rules when writing, reviewing,
 - 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.
 
+## 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` and the relevant `local-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
@@ -286,6 +296,13 @@ bash scripts/validate-csharp-naming.sh
 
 - Update the relevant `README.md` or `docs/` page when behavior, setup steps, architecture guidance, or user-facing
   examples change.
+- 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 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.

diff --git a/GFramework.csproj b/GFramework.csproj
@@ -70,16 +70,17 @@
         <None Remove="GFramework.Cqrs.Abstractions\**"/>
         <None Remove="GFramework.Cqrs.Tests\**"/>
         <None Remove="GFramework.Tests.Common\**"/>
+        <None Remove="ai-libs\**" />
     </ItemGroup>
     <!-- 聚合核心模块 -->
     <ItemGroup>
-        <ProjectReference Include="GFramework.Core\GFramework.Core.csproj"/>
-        <ProjectReference Include="GFramework.Game\GFramework.Game.csproj"/>
+        <ProjectReference Include="GFramework.Core\GFramework.Core.csproj" />
+        <ProjectReference Include="GFramework.Game\GFramework.Game.csproj" />
     </ItemGroup>
     <ItemGroup>
-        <Compile Remove="GFramework.Core\**"/>
-        <Compile Remove="GFramework.Game\**"/>
-        <Compile Remove="GFramework.Godot\**"/>
+        <Compile Remove="GFramework.Core\**" />
+        <Compile Remove="GFramework.Game\**" />
+        <Compile Remove="GFramework.Godot\**" />
         <Compile Update="GFramework.Core.SourceGenerators\enums\EnumExtensionsGenerator.cs">
             <Link>GFramework.Core.SourceGenerators\enums\EnumExtensionsGenerator.cs</Link>
         </Compile>
@@ -89,69 +90,71 @@
         <Compile Update="GFramework.Core.SourceGenerators\logging\LoggerGenerator.cs">
             <Link>GFramework.Core.SourceGenerators\logging\LoggerGenerator.cs</Link>
         </Compile>
-        <Compile Remove="GFramework.Godot.SourceGenerators\**"/>
-        <Compile Remove="GFramework.SourceGenerators\**"/>
-        <Compile Remove="GFramework.Core.SourceGenerators\**"/>
-        <Compile Remove="GFramework.Core.SourceGenerators.Abstractions\**"/>
-        <Compile Remove="GFramework.Cqrs.SourceGenerators\**"/>
-        <Compile Remove="GFramework.Game.SourceGenerators\**"/>
-        <Compile Remove="GFramework.SourceGenerators.Common\**"/>
-        <Compile Remove="GFramework.SourceGenerators.Tests\**"/>
-        <Compile Remove="GFramework.Godot.SourceGenerators.Tests\**"/>
-        <Compile Remove="GFramework.Godot.SourceGenerators.Abstractions\**"/>
-        <Compile Remove="GFramework.SourceGenerators.Abstractions\**"/>
-        <Compile Remove="GFramework.Core.Abstractions\**"/>
-        <Compile Remove="GFramework.Godot.Abstractions\**"/>
-        <Compile Remove="GFramework.Game.Abstractions\**"/>
-        <Compile Remove="GFramework.Core.Tests\**"/>
-        <Compile Remove="GFramework.Ecs.Arch.Tests\**"/>
-        <Compile Remove="GFramework.Ecs.Arch\**"/>
-        <Compile Remove="GFramework.Ecs.Arch.Abstractions\**"/>
-        <Compile Remove="GFramework.Generator\**"/>
-        <Compile Remove="GFramework.Generator.Attributes\**"/>
-        <Compile Remove="GFramework.Godot.SourceGenerators.Attributes\**"/>
-        <Compile Remove="GFramework.SourceGenerators.Attributes\**"/>
-        <Compile Remove="Godot\**"/>
-        <Compile Remove="GFramework.Game.Tests\**"/>
-        <Compile Remove="GFramework.Godot.Tests\**"/>
-        <Compile Remove="GFramework.Cqrs\**"/>
-        <Compile Remove="GFramework.Cqrs.Abstractions\**"/>
-        <Compile Remove="GFramework.Cqrs.Tests\**"/>
-        <Compile Remove="GFramework.Tests.Common\**"/>
+        <Compile Remove="GFramework.Godot.SourceGenerators\**" />
+        <Compile Remove="GFramework.SourceGenerators\**" />
+        <Compile Remove="GFramework.Core.SourceGenerators\**" />
+        <Compile Remove="GFramework.Core.SourceGenerators.Abstractions\**" />
+        <Compile Remove="GFramework.Cqrs.SourceGenerators\**" />
+        <Compile Remove="GFramework.Game.SourceGenerators\**" />
+        <Compile Remove="GFramework.SourceGenerators.Common\**" />
+        <Compile Remove="GFramework.SourceGenerators.Tests\**" />
+        <Compile Remove="GFramework.Godot.SourceGenerators.Tests\**" />
+        <Compile Remove="GFramework.Godot.SourceGenerators.Abstractions\**" />
+        <Compile Remove="GFramework.SourceGenerators.Abstractions\**" />
+        <Compile Remove="GFramework.Core.Abstractions\**" />
+        <Compile Remove="GFramework.Godot.Abstractions\**" />
+        <Compile Remove="GFramework.Game.Abstractions\**" />
+        <Compile Remove="GFramework.Core.Tests\**" />
+        <Compile Remove="GFramework.Ecs.Arch.Tests\**" />
+        <Compile Remove="GFramework.Ecs.Arch\**" />
+        <Compile Remove="GFramework.Ecs.Arch.Abstractions\**" />
+        <Compile Remove="GFramework.Generator\**" />
+        <Compile Remove="GFramework.Generator.Attributes\**" />
+        <Compile Remove="GFramework.Godot.SourceGenerators.Attributes\**" />
+        <Compile Remove="GFramework.SourceGenerators.Attributes\**" />
+        <Compile Remove="Godot\**" />
+        <Compile Remove="GFramework.Game.Tests\**" />
+        <Compile Remove="GFramework.Godot.Tests\**" />
+        <Compile Remove="GFramework.Cqrs\**" />
+        <Compile Remove="GFramework.Cqrs.Abstractions\**" />
+        <Compile Remove="GFramework.Cqrs.Tests\**" />
+        <Compile Remove="GFramework.Tests.Common\**" />
+        <Compile Remove="ai-libs\**" />
     </ItemGroup>
     <ItemGroup>
-        <EmbeddedResource Remove="GFramework.Core\**"/>
-        <EmbeddedResource Remove="GFramework.Game\**"/>
-        <EmbeddedResource Remove="GFramework.Godot\**"/>
-        <EmbeddedResource Remove="GFramework.Godot.SourceGenerators\**"/>
-        <EmbeddedResource Remove="GFramework.SourceGenerators\**"/>
-        <EmbeddedResource Remove="GFramework.Core.SourceGenerators\**"/>
-        <EmbeddedResource Remove="GFramework.Core.SourceGenerators.Abstractions\**"/>
-        <EmbeddedResource Remove="GFramework.Cqrs.SourceGenerators\**"/>
-        <EmbeddedResource Remove="GFramework.Game.SourceGenerators\**"/>
-        <EmbeddedResource Remove="GFramework.SourceGenerators.Common\**"/>
-        <EmbeddedResource Remove="GFramework.SourceGenerators.Tests\**"/>
-        <EmbeddedResource Remove="GFramework.Godot.SourceGenerators.Tests\**"/>
-        <EmbeddedResource Remove="GFramework.Godot.SourceGenerators.Abstractions\**"/>
-        <EmbeddedResource Remove="GFramework.SourceGenerators.Abstractions\**"/>
-        <EmbeddedResource Remove="GFramework.Core.Abstractions\**"/>
-        <EmbeddedResource Remove="GFramework.Godot.Abstractions\**"/>
-        <EmbeddedResource Remove="GFramework.Game.Abstractions\**"/>
-        <EmbeddedResource Remove="GFramework.Core.Tests\**"/>
-        <EmbeddedResource Remove="GFramework.Ecs.Arch.Tests\**"/>
-        <EmbeddedResource Remove="GFramework.Ecs.Arch\**"/>
-        <EmbeddedResource Remove="GFramework.Ecs.Arch.Abstractions\**"/>
-        <EmbeddedResource Remove="GFramework.Generator\**"/>
-        <EmbeddedResource Remove="GFramework.Generator.Attributes\**"/>
-        <EmbeddedResource Remove="GFramework.Godot.SourceGenerators.Attributes\**"/>
-        <EmbeddedResource Remove="GFramework.SourceGenerators.Attributes\**"/>
-        <EmbeddedResource Remove="Godot\**"/>
-        <EmbeddedResource Remove="GFramework.Game.Tests\**"/>
-        <EmbeddedResource Remove="GFramework.Godot.Tests\**"/>
-        <EmbeddedResource Remove="GFramework.Cqrs\**"/>
-        <EmbeddedResource Remove="GFramework.Cqrs.Abstractions\**"/>
-        <EmbeddedResource Remove="GFramework.Cqrs.Tests\**"/>
-        <EmbeddedResource Remove="GFramework.Tests.Common\**"/>
+        <EmbeddedResource Remove="GFramework.Core\**" />
+        <EmbeddedResource Remove="GFramework.Game\**" />
+        <EmbeddedResource Remove="GFramework.Godot\**" />
+        <EmbeddedResource Remove="GFramework.Godot.SourceGenerators\**" />
+        <EmbeddedResource Remove="GFramework.SourceGenerators\**" />
+        <EmbeddedResource Remove="GFramework.Core.SourceGenerators\**" />
+        <EmbeddedResource Remove="GFramework.Core.SourceGenerators.Abstractions\**" />
+        <EmbeddedResource Remove="GFramework.Cqrs.SourceGenerators\**" />
+        <EmbeddedResource Remove="GFramework.Game.SourceGenerators\**" />
+        <EmbeddedResource Remove="GFramework.SourceGenerators.Common\**" />
+        <EmbeddedResource Remove="GFramework.SourceGenerators.Tests\**" />
+        <EmbeddedResource Remove="GFramework.Godot.SourceGenerators.Tests\**" />
+        <EmbeddedResource Remove="GFramework.Godot.SourceGenerators.Abstractions\**" />
+        <EmbeddedResource Remove="GFramework.SourceGenerators.Abstractions\**" />
+        <EmbeddedResource Remove="GFramework.Core.Abstractions\**" />
+        <EmbeddedResource Remove="GFramework.Godot.Abstractions\**" />
+        <EmbeddedResource Remove="GFramework.Game.Abstractions\**" />
+        <EmbeddedResource Remove="GFramework.Core.Tests\**" />
+        <EmbeddedResource Remove="GFramework.Ecs.Arch.Tests\**" />
+        <EmbeddedResource Remove="GFramework.Ecs.Arch\**" />
+        <EmbeddedResource Remove="GFramework.Ecs.Arch.Abstractions\**" />
+        <EmbeddedResource Remove="GFramework.Generator\**" />
+        <EmbeddedResource Remove="GFramework.Generator.Attributes\**" />
+        <EmbeddedResource Remove="GFramework.Godot.SourceGenerators.Attributes\**" />
+        <EmbeddedResource Remove="GFramework.SourceGenerators.Attributes\**" />
+        <EmbeddedResource Remove="Godot\**" />
+        <EmbeddedResource Remove="GFramework.Game.Tests\**" />
+        <EmbeddedResource Remove="GFramework.Godot.Tests\**" />
+        <EmbeddedResource Remove="GFramework.Cqrs\**" />
+        <EmbeddedResource Remove="GFramework.Cqrs.Abstractions\**" />
+        <EmbeddedResource Remove="GFramework.Cqrs.Tests\**" />
+        <EmbeddedResource Remove="GFramework.Tests.Common\**" />
+        <EmbeddedResource Remove="ai-libs\**" />
     </ItemGroup>
     <ItemGroup>
         <AdditionalFiles Remove="AnalyzerReleases.Shipped.md"/>

diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md
@@ -434,9 +434,11 @@ Godot 引擎集成模块。
 
 ## 源码生成器
 
-### GFramework.SourceGenerators
+### Source Generators 家族
 
-自动代码生成工具。
+自动代码生成工具按模块拆分为 `GFramework.Core.SourceGenerators`、`GFramework.Game.SourceGenerators`、
+`GFramework.Godot.SourceGenerators` 与 `GFramework.Cqrs.SourceGenerators`。面向业务代码声明的 Attribute
+主要来自 `GFramework.Core.SourceGenerators.Abstractions.*` 与对应模块的 runtime/generator 包。
 
 #### 支持的生成器
 

diff --git a/docs/zh-CN/best-practices/architecture-patterns.md b/docs/zh-CN/best-practices/architecture-patterns.md
@@ -657,7 +657,7 @@ public partial class UIController : IController
 ### 事件组合
 
 ```csharp
-using GFramework.SourceGenerators.Abstractions.Rule;
+using GFramework.Core.SourceGenerators.Abstractions.Rule;
 
 // 使用 OrEvent 组合多个事件
 [ContextAware]

diff --git a/docs/zh-CN/best-practices/index.md b/docs/zh-CN/best-practices/index.md
@@ -33,7 +33,7 @@ public class CombatSystem : AbstractSystem
 }
 
 using GFramework.Core.Abstractions.Controller;
-using GFramework.SourceGenerators.Abstractions.Rule;
+using GFramework.Core.SourceGenerators.Abstractions.Rule;
 
 [ContextAware]
 public partial class PlayerController : IController
@@ -182,7 +182,7 @@ public class StorageUtility : IUtility { }
 
 ```csharp
 using GFramework.Core.Abstractions.Controller;
-using GFramework.SourceGenerators.Abstractions.Rule;
+using GFramework.Core.SourceGenerators.Abstractions.Rule;
 
 [ContextAware]
 public partial class MyController : IController

diff --git a/docs/zh-CN/best-practices/performance.md b/docs/zh-CN/best-practices/performance.md
@@ -278,7 +278,7 @@ public class PoolMonitorSystem : AbstractSystem
 
 ```csharp
 using GFramework.Core.Abstractions.Controller;
-using GFramework.SourceGenerators.Abstractions.Rule;
+using GFramework.Core.SourceGenerators.Abstractions.Rule;
 
 // ✅ 好的做法：正确管理事件订阅
 [ContextAware]

diff --git a/docs/zh-CN/core/command.md b/docs/zh-CN/core/command.md
@@ -57,7 +57,7 @@ public class SimpleCommand : AbstractCommand
 
 // 使用命令
 using GFramework.Core.Abstractions.Controller;
-using GFramework.SourceGenerators.Abstractions.Rule;
+using GFramework.Core.SourceGenerators.Abstractions.Rule;
 
 [ContextAware]
 public partial class GameController : IController
@@ -221,7 +221,7 @@ public class StartGameCommand : AbstractCommand<StartGameInput>
 
 // 使用命令
 using GFramework.Core.Abstractions.Controller;
-using GFramework.SourceGenerators.Abstractions.Rule;
+using GFramework.Core.SourceGenerators.Abstractions.Rule;
 
 [ContextAware]
 public partial class GameController : IController

diff --git a/docs/zh-CN/core/configuration.md b/docs/zh-CN/core/configuration.md
@@ -622,7 +622,7 @@ public class SettingsSystem : AbstractSystem
 ### 在 Controller 中使用
 
 ```csharp
-using GFramework.SourceGenerators.Abstractions.Rule;
+using GFramework.Core.SourceGenerators.Abstractions.Rule;
 
 [ContextAware]
 public partial class SettingsController : IController