Merge pull request #120 from GeWuYou/feat/docs-add-repository-guide

docs(guide): 添加仓库开发指南文档

AGENTS.md

@@ -0,0 +1,42 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`GFramework.sln` is the entry point for the full .NET solution. Runtime code lives in `GFramework.Core/`,
+`GFramework.Game/`, `GFramework.Godot/`, and `GFramework.Ecs.Arch/`. Interface-only contracts stay in the paired
+`*.Abstractions/` projects. Roslyn generators are split across `GFramework.SourceGenerators/`,
+`GFramework.Godot.SourceGenerators/`, and `GFramework.SourceGenerators.Common/`. Tests mirror the runtime modules in
+`GFramework.Core.Tests/`, `GFramework.Game.Tests/`, `GFramework.Ecs.Arch.Tests/`, and
+`GFramework.SourceGenerators.Tests/`. Documentation is under `docs/`, Godot templates under `Godot/script_templates/`,
+and repository utilities under `scripts/` and `refactor-scripts/`.
+
+## Build, Test, and Development Commands
+
+- `dotnet build GFramework.sln` builds the full solution from the repo root.
+- `dotnet test GFramework.sln --no-build` runs all NUnit test projects after a build.
+- `dotnet test GFramework.Core.Tests --filter "FullyQualifiedName~CommandExecutorTests.Execute"` runs a focused NUnit
+  test.
+- `bash scripts/validate-csharp-naming.sh` checks PascalCase namespace and directory rules used by CI.
+- `cd docs && bun install && bun run dev` starts the VitePress docs site locally.
+
+## Coding Style & Naming Conventions
+
+Use standard C# formatting with 4-space indentation and one public type per file. The repository keeps `ImplicitUsings`
+disabled and `Nullable` enabled, so write explicit `using` directives and annotate nullability carefully. Follow
+`PascalCase` for types, methods, namespaces, directories, and constants; use `_camelCase` for private fields and
+`camelCase` for locals and parameters. Keep namespaces aligned with folders, for example
+`GFramework.Core.Architectures`.
+
+## Testing Guidelines
+
+Tests use NUnit 4 with `Microsoft.NET.Test.Sdk`; some suites also use Moq. Place tests in the matching module test
+project and name files `*Tests.cs`. Prefer directory parity with production code, for example `GFramework.Core/Logging/`
+and `GFramework.Core.Tests/Logging/`. Add or update tests for every behavior change, especially public APIs, source
+generators, and integration paths.
+
+## Commit & Pull Request Guidelines
+
+Recent history follows Conventional Commits style such as `feat(events): ...`, `refactor(localization): ...`,
+`docs(guide): ...`, and `test(localization): ...`. Keep commits scoped and imperative. PRs should explain the
+motivation, implementation, and validation commands run; link related issues; and include screenshots when docs, UI, or
+Godot-facing behavior changes.

GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj

@@ -17,7 +17,7 @@
         <Using Include="GFramework.Core.Abstractions"/>
     </ItemGroup>
     <ItemGroup>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
             <PrivateAssets>all</PrivateAssets>
             <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
         </PackageReference>

GFramework.Core.Tests/GFramework.Core.Tests.csproj

@@ -21,6 +21,7 @@
     </ItemGroup>
 
     <ItemGroup>
+      <PackageReference Include="Scriban" Version="6.6.0" />
         <ProjectReference Include="..\GFramework.Core\GFramework.Core.csproj"/>
         <ProjectReference Include="..\GFramework.SourceGenerators.Abstractions\GFramework.SourceGenerators.Abstractions.csproj"/>
         <ProjectReference Include="..\GFramework.SourceGenerators.Common\GFramework.SourceGenerators.Common.csproj"/>

GFramework.Core/GFramework.Core.csproj

@@ -11,7 +11,7 @@
         <ProjectReference Include="..\$(AssemblyName).Abstractions\$(AssemblyName).Abstractions.csproj"/>
     </ItemGroup>
     <ItemGroup>
-        <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.4"/>
+        <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.5"/>
         <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" Version="8.0.0"/>
     </ItemGroup>
 </Project>

GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj

@@ -19,7 +19,7 @@
         <Using Include="GFramework.Game.Abstractions"/>
     </ItemGroup>
     <ItemGroup>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
             <PrivateAssets>all</PrivateAssets>
             <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
         </PackageReference>

GFramework.Godot.SourceGenerators.Abstractions/GFramework.Godot.SourceGenerators.Abstractions.csproj

@@ -19,7 +19,7 @@
         <Folder Include="logging\"/>
     </ItemGroup>
     <ItemGroup>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
             <PrivateAssets>all</PrivateAssets>
             <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
         </PackageReference>

GFramework.SourceGenerators.Abstractions/GFramework.SourceGenerators.Abstractions.csproj

@@ -18,7 +18,7 @@
         <ProjectReference Include="..\GFramework.Core.Abstractions\GFramework.Core.Abstractions.csproj" PrivateAssets="all"/>
     </ItemGroup>
     <ItemGroup>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
             <PrivateAssets>all</PrivateAssets>
             <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
         </PackageReference>

GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj

@@ -22,7 +22,7 @@
             <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
         </PackageReference>
         <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" PrivateAssets="all"/>
-        <PackageReference Update="Meziantou.Analyzer" Version="3.0.19">
+        <PackageReference Update="Meziantou.Analyzer" Version="3.0.25">
             <PrivateAssets>all</PrivateAssets>
             <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
         </PackageReference>