docs(sdk): 更新文档规范并添加VitePress配置

AGENTS.md

@@ -237,23 +237,32 @@ 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.
 
-### Task Tracking
-
-- When working from a tracked implementation plan, contributors MUST update the corresponding tracking document under
-  `local-plan/todos/` in the same change.
-- Tracking updates MUST reflect completed work, newly discovered issues, validation results, and the next recommended
-  recovery point.
-- 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 `local-plan/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 `local-plan/traces/` for complex work. The trace should
-  record the current date, key decisions, validation milestones, and the immediate next step.
-- 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 Source Of Truth
+
+- Treat source code, `*.csproj`, tests, generated snapshots, and packaging metadata as the primary evidence for
+  documentation updates.
+- Treat `CoreGrid` 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
 
@@ -273,6 +282,32 @@ bash scripts/validate-csharp-naming.sh
   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
+
+- When working from a tracked implementation plan, contributors MUST update the corresponding tracking document under
+  `local-plan/todos/` in the same change.
+- Tracking updates MUST reflect completed work, newly discovered issues, validation results, and the next recommended
+  recovery point.
+- 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 `local-plan/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 `local-plan/traces/` for complex work. The trace should
+  record the current date, key decisions, validation milestones, and the immediate next step.
+- 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
 

GFramework.Core.Abstractions/README.md

@@ -1,27 +1,51 @@
 # GFramework.Core.Abstractions
 
-GFramework 框架的抽象层定义模块，包含所有核心组件的接口定义。
+`GFramework.Core.Abstractions` 承载 `Core` 运行时对应的接口、枚举和值对象，用来定义跨模块协作边界。
 
-## 主要内容
+## 什么时候单独依赖它
 
-- 架构核心接口 (IArchitecture, IArchitectureContext等)
-- 数据模型接口 (IModel)
-- 业务系统接口 (ISystem)
-- 控制器接口 (IController)
-- 命令与查询接口 (ICommand, IQuery)
-- 事件系统接口 (IEvent, IEventBus)
-- 依赖注入容器接口 (IIocContainer)
-- 可绑定属性接口 (IBindableProperty)
-- 状态管理接口 (IStore, IReducer, IStateSelector, IStoreBuilder)
-- 日志系统接口 (ILogger)
+- 你在做插件、适配层或扩展包，只想依赖契约，不想把完整运行时拉进来
+- 你需要为测试、编辑器工具或生成器提供替身实现
+- 你在做多模块拆分，希望上层只面向接口编程
 
-## 设计原则
+如果你只是直接使用框架功能，优先安装 `GFramework.Core`。
 
-- 接口隔离，每个接口职责单一
-- 依赖倒置，上层依赖抽象接口
-- 类型安全，充分利用泛型系统
-- 广泛兼容，基于 netstandard2.0
+## 包关系
 
-## 详细文档
+- 契约层：`GFramework.Core.Abstractions`
+- 实现层：`GFramework.Core`
+- 相关扩展：
+  - `GFramework.Cqrs.Abstractions`
+  - `GFramework.Game.Abstractions`
 
-参见 [docs/zh-CN/abstractions/](../docs/zh-CN/abstractions/) 目录下的详细文档。
+## 契约地图
+
+| 目录 | 作用 |
+| --- | --- |
+| `Architectures/` | `IArchitecture`、模块、阶段监听与服务管理契约 |
+| `Command/` / `Query/` | 旧版命令与查询执行器接口 |
+| `Controller/` | `IController` |
+| `Events/` | 事件契约、解绑接口与传播上下文 |
+| `Model/` / `Systems/` / `Utility/` | 核心组件接口 |
+| `State/` / `StateManagement/` | 状态机、Store、reducer、selector 契约 |
+| `Property/` | `IBindableProperty` 与只读属性接口 |
+| `Resource/` | 资源管理与释放策略契约 |
+| `Localization/` | 本地化表、格式化与异常类型 |
+| `Logging/` | logger、log entry、factory 相关契约 |
+| `Ioc/` | `IIocContainer` |
+| `Lifecycle/` | 初始化 / 销毁生命周期契约 |
+| `Coroutine/` | 时间源、yield 指令与协程状态枚举 |
+| `Pause/` | 暂停栈、token 与状态事件 |
+| `Storage/` / `Serializer/` / `Versioning/` | 通用存储、序列化与版本化契约 |
+
+## 采用建议
+
+- 框架消费者通常同时安装 `GFramework.Core` 与 `GFramework.Core.Abstractions`
+- 若你只需要对接口编程，可以仅引用本包，再在应用层自行提供实现
+- 若你在写上层模块，优先把公共契约放在 `*.Abstractions`，实现放在对应 runtime 包
+
+## 对应文档
+
+- 抽象接口栏目：[`../docs/zh-CN/abstractions/index.md`](../docs/zh-CN/abstractions/index.md)
+- Core 抽象页：[`../docs/zh-CN/abstractions/core-abstractions.md`](../docs/zh-CN/abstractions/core-abstractions.md)
+- Core 运行时入口：[`../GFramework.Core/README.md`](../GFramework.Core/README.md)

GFramework.Core.SourceGenerators/README.md

@@ -1,63 +1,95 @@
-# GFramework.SourceGenerators
+# GFramework.Core.SourceGenerators
 
-Core 侧通用源码生成器模块。
+`GFramework.Core.SourceGenerators` 承载 Core 侧的通用源码生成器与分析器，用来减少样板代码并把部分约束前移到编译期。
 
-## Context Get 注入
+## 模块定位
 
-当类本身是上下文感知类型时，可以通过字段特性生成一个手动调用的注入方法：
+这个包属于编译期工具链，不是运行时库。
 
-- `[GetService]`
-- `[GetServices]`
-- `[GetSystem]`
-- `[GetSystems]`
+当前仓库中的主要目录：
+
+- `Architectures/`
+- `Analyzers/`
+- `Bases/`
+- `Enums/`
+- `Logging/`
+- `Rule/`
+- `Diagnostics/`
+
+对应的生成器家族主要包括：
+
+- 日志相关生成器
+- `ContextAware` 及上下文注入辅助
+- 枚举扩展生成器
+- 优先级相关生成器
+- 模块自动注册
+- 注册可见性分析器
+
+## 包关系
+
+- 运行时：`GFramework.Core`
+- 契约与特性：`GFramework.Core.SourceGenerators.Abstractions`
+- 公共生成器支撑：`GFramework.SourceGenerators.Common`
+
+如果你还需要游戏配置 schema 生成或 Godot 专用生成器，应分别安装：
+
+- `GFramework.Game.SourceGenerators`
+- `GFramework.Godot.SourceGenerators`
+
+## 主要能力
+
+### 上下文注入与 `ContextAware`
+
+该包支持围绕上下文感知类型生成辅助代码，例如：
+
+- `[ContextAware]`
 - `[GetModel]`
 - `[GetModels]`
+- `[GetSystem]`
+- `[GetSystems]`
 - `[GetUtility]`
 - `[GetUtilities]`
+- `[GetService]`
+- `[GetServices]`
 - `[GetAll]`
 
-上下文感知类满足以下任一条件即可：
+这类生成器适合用于 View、Controller、Godot 节点包装或其他需要频繁访问架构上下文的类型。
 
-- 类上带有 `[ContextAware]`
-- 继承 `ContextAwareBase`
-- 实现 `IContextAware`
+### 日志辅助
 
-生成器会生成 `__InjectContextBindings_Generated()`，需要在合适的生命周期中手动调用。在 Godot 中通常放在 `_Ready()`：
+支持通过生成器减少 `ILogger` 相关样板代码。
 
-```csharp
-using GFramework.SourceGenerators.Abstractions.Rule;
+### 注册分析器
 
-[ContextAware]
-public partial class InventoryPanel
-{
-    [GetModel]
-    private IInventoryModel _inventory = null!;
+包内还包含分析器，用来检查 `Model`、`System`、`Utility` 的使用点是否能在所属架构中找到静态可见注册，帮助尽早发现“代码可以编译、运行时却缺注册”的问题。
 
-    [GetServices]
-    private IReadOnlyList<IInventoryStrategy> _strategies = null!;
+## 最小接入路径
 
-    public override void _Ready()
-    {
-        __InjectContextBindings_Generated();
-    }
-}
+```xml
+<ItemGroup>
+  <PackageReference Include="GeWuYou.GFramework.Core.SourceGenerators"
+                    Version="x.y.z"
+                    PrivateAssets="all"
+                    ExcludeAssets="runtime" />
+</ItemGroup>
 ```
 
-`[GetAll]` 作用于类本身，会自动扫描字段并推断 `Model`、`System`、`Utility` 相关的 `GetX` 调用；已显式标记字段的优先级更高。
+如果你想查看生成代码，可在消费者项目里启用：
 
-`Service` 和 `Services` 绑定不会在 `[GetAll]` 下自动推断。对于普通引用类型字段，请显式使用 `[GetService]` 或
-`[GetServices]`，避免将非上下文服务字段误判为服务依赖。
-
-`[GetAll]` 会跳过 `const`、`static` 和 `readonly` 字段。若某个字段本来会被 `[GetAll]` 推断为
-`Model`、`System` 或 `Utility` 绑定，但因为是不可赋值的 `static` 或 `readonly` 字段而被跳过，生成器会发出警告提示该字段不会参与生成。
+```xml
+<PropertyGroup>
+  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
+  <CompilerGeneratedFilesOutputPath>Generated</CompilerGeneratedFilesOutputPath>
+</PropertyGroup>
+```
 
-## 注册分析器
+## 适用场景
 
-包现在同时包含一个注册可见性分析器，用于检查 `Model`、`System`、`Utility` 的使用点是否能在所属架构中找到静态可见注册。
+- 你希望减少上下文绑定与日志相关样板代码
+- 你需要在编译期发现部分注册可见性问题
+- 你在做模块化架构，希望固定某些重复注册模式
 
-- 覆盖字段特性注入：`[GetModel]`、`[GetModels]`、`[GetSystem]`、`[GetSystems]`、`[GetUtility]`、`[GetUtilities]`
-- 覆盖手写调用：`GetModel<T>()`、`GetModels<T>()`、`GetSystem<T>()`、`GetSystems<T>()`、`GetUtility<T>()`、`GetUtilities<T>()`
-- 默认报告 `Warning`
-- 当前只分析静态可见的注册路径，例如 `OnInitialize()`、`InstallModules()`、`InstallModule(new Module())`
+## 对应文档
 
-对于反射、运行时条件分支、外部程序集动态注册等路径，分析器不会强行推断；当无法唯一确定组件所属架构时，也会选择不报，优先降低误报。
+- 源码生成器总览：[`../docs/zh-CN/source-generators/index.md`](../docs/zh-CN/source-generators/index.md)
+- Core 栏目：[`../docs/zh-CN/core/index.md`](../docs/zh-CN/core/index.md)