From 9cca190aff3312d79877b0a62824d75c3a0d784f Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Tue, 31 Mar 2026 10:03:31 +0800
Subject: [PATCH] =?UTF-8?q?docs(generator):=20=E6=B7=BB=E5=8A=A0=E6=BA=90?=
 =?UTF-8?q?=E7=A0=81=E7=94=9F=E6=88=90=E5=99=A8=E6=96=87=E6=A1=A3=E5=92=8C?=
 =?UTF-8?q?=E5=88=86=E6=9E=90=E5=99=A8=E8=A7=84=E5=88=99=E6=B8=85=E5=8D=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 AnalyzerReleases.Unshipped.md 文件记录代码分析规则
- 添加 GF_Godot_GetNode 系列规则定义（001-006）
- 添加 GF_Godot_BindNodeSignal 系列规则定义（001-009）
- 创建 README.md 文件详述源码生成器使用方法
- 文档化 GetNode 和 BindNodeSignal 特性用法示例
- 说明 Godot 场景相关的编译期生成能力
---
 .../AnalyzerReleases.Unshipped.md             | 25 +++++++----
 GFramework.Godot.SourceGenerators/README.md   | 45 +++++++++++++++++++
 2 files changed, 62 insertions(+), 8 deletions(-)

diff --git a/GFramework.Godot.SourceGenerators/AnalyzerReleases.Unshipped.md b/GFramework.Godot.SourceGenerators/AnalyzerReleases.Unshipped.md
index a78788c..b478e72 100644
--- a/GFramework.Godot.SourceGenerators/AnalyzerReleases.Unshipped.md
+++ b/GFramework.Godot.SourceGenerators/AnalyzerReleases.Unshipped.md
@@ -3,11 +3,20 @@
 
 ### New Rules
 
- Rule ID              | Category         | Severity | Notes              
-----------------------|------------------|----------|--------------------
- GF_Godot_GetNode_001 | GFramework.Godot | Error    | GetNodeDiagnostics 
- GF_Godot_GetNode_002 | GFramework.Godot | Error    | GetNodeDiagnostics 
- GF_Godot_GetNode_003 | GFramework.Godot | Error    | GetNodeDiagnostics 
- GF_Godot_GetNode_004 | GFramework.Godot | Error    | GetNodeDiagnostics 
- GF_Godot_GetNode_005 | GFramework.Godot | Error    | GetNodeDiagnostics 
- GF_Godot_GetNode_006 | GFramework.Godot | Warning  | GetNodeDiagnostics 
\ No newline at end of file
+ Rule ID                     | Category         | Severity | Notes                     
+-----------------------------|------------------|----------|---------------------------
+ GF_Godot_GetNode_001        | GFramework.Godot | Error    | GetNodeDiagnostics        
+ GF_Godot_GetNode_002        | GFramework.Godot | Error    | GetNodeDiagnostics        
+ GF_Godot_GetNode_003        | GFramework.Godot | Error    | GetNodeDiagnostics        
+ GF_Godot_GetNode_004        | GFramework.Godot | Error    | GetNodeDiagnostics        
+ GF_Godot_GetNode_005        | GFramework.Godot | Error    | GetNodeDiagnostics        
+ GF_Godot_GetNode_006        | GFramework.Godot | Warning  | GetNodeDiagnostics        
+ GF_Godot_BindNodeSignal_001 | GFramework.Godot | Error    | BindNodeSignalDiagnostics 
+ GF_Godot_BindNodeSignal_002 | GFramework.Godot | Error    | BindNodeSignalDiagnostics 
+ GF_Godot_BindNodeSignal_003 | GFramework.Godot | Error    | BindNodeSignalDiagnostics 
+ GF_Godot_BindNodeSignal_004 | GFramework.Godot | Error    | BindNodeSignalDiagnostics 
+ GF_Godot_BindNodeSignal_005 | GFramework.Godot | Error    | BindNodeSignalDiagnostics 
+ GF_Godot_BindNodeSignal_006 | GFramework.Godot | Error    | BindNodeSignalDiagnostics 
+ GF_Godot_BindNodeSignal_007 | GFramework.Godot | Error    | BindNodeSignalDiagnostics 
+ GF_Godot_BindNodeSignal_008 | GFramework.Godot | Warning  | BindNodeSignalDiagnostics 
+ GF_Godot_BindNodeSignal_009 | GFramework.Godot | Warning  | BindNodeSignalDiagnostics 
diff --git a/GFramework.Godot.SourceGenerators/README.md b/GFramework.Godot.SourceGenerators/README.md
index 291c557..87f423d 100644
--- a/GFramework.Godot.SourceGenerators/README.md
+++ b/GFramework.Godot.SourceGenerators/README.md
@@ -7,6 +7,7 @@
 - 与 Godot 场景相关的编译期生成能力
 - 基于 Roslyn 的增量生成器实现
 - `[GetNode]` 字段注入，减少 `_Ready()` 里的 `GetNode<T>()` 样板代码
+- `[BindNodeSignal]` 方法绑定，减少 `_Ready()` / `_ExitTree()` 中重复的事件订阅样板代码
 
 ## 使用建议
 
@@ -43,3 +44,47 @@ public partial class TopBar : HBoxContainer
 
 - `_leftContainer` -> `%LeftContainer`
 - `m_rightContainer` -> `%RightContainer`
+
+## BindNodeSignal 用法
+
+```csharp
+using GFramework.Godot.SourceGenerators.Abstractions;
+using Godot;
+
+public partial class Hud : Control
+{
+    [GetNode]
+    private Button _startButton = null!;
+
+    [GetNode]
+    private SpinBox _startOreSpinBox = null!;
+
+    [BindNodeSignal(nameof(_startButton), nameof(Button.Pressed))]
+    private void OnStartButtonPressed()
+    {
+    }
+
+    [BindNodeSignal(nameof(_startOreSpinBox), nameof(SpinBox.ValueChanged))]
+    private void OnStartOreValueChanged(double value)
+    {
+    }
+
+    public override void _Ready()
+    {
+        __InjectGetNodes_Generated();
+        __BindNodeSignals_Generated();
+    }
+
+    public override void _ExitTree()
+    {
+        __UnbindNodeSignals_Generated();
+    }
+}
+```
+
+生成器会产出两个辅助方法：
+
+- `__BindNodeSignals_Generated()`：负责统一订阅事件
+- `__UnbindNodeSignals_Generated()`：负责统一解绑事件
+
+当前设计只处理 CLR event 形式的 Godot 事件绑定，不会自动调用 `Connect()` / `Disconnect()`。