docs: 按 Godot 规范优化全部 GDScript 注释

- 类/信号/方法添加 ## 文档注释与 @param 标签
- 清理 pass 占位残留

src/UI/HUD/top_bar_hud.gd

@@ -1,9 +1,15 @@
+## 顶部信息栏 HUD（挂载于 TopBarHUD.tscn）。
+## 显示灵石/时间/声望，提供时间流速控制与返回主菜单入口。
 extends Control
 
+## 请求返回主菜单。
 signal sign_return_mainmenu
 
+## 三个流速按钮的节点名（与 tscn 中的 SpeedGroup 子节点对应）。
 const SPEED_BUTTONS := ["Button_Speed1", "Button_Speed5", "Button_Speed20"]
+## 激活档位按钮颜色。
 const ACTIVE_COLOR := Color(1.0, 1.0, 1.0)
+## 未激活档位按钮颜色。
 const INACTIVE_COLOR := Color(0.55, 0.55, 0.55)
 
 func _ready() -> void:
@@ -14,20 +20,26 @@ func _ready() -> void:
 	_update_speed_ui()
 	$HBoxContainer/Value_Time.text = TimeSystem.get_date_text()
 
+## 每日推进时刷新日期显示。
 func _on_day_passed(_year: int, _month: int, _day: int) -> void:
 	$HBoxContainer/Value_Time.text = TimeSystem.get_date_text()
 
+## 点击"返回"按钮。
 func _on_button_return_button_up() -> void:
 	sign_return_mainmenu.emit()
 
+## 点击暂停/继续按钮，切换后刷新按钮状态。
 func _on_button_pause_button_up() -> void:
 	TimeSystem.toggle_pause()
 	_update_speed_ui()
 
+## 点击流速档位按钮。
+## @param index: 目标档位索引（由 _ready 中 bind 传入）
 func _on_speed_button_up(index: int) -> void:
 	TimeSystem.set_speed_index(index)
 	_update_speed_ui()
 
+## 刷新速度组 UI：暂停按钮文字与各档位高亮状态。
 func _update_speed_ui() -> void:
 	var pause_btn: Button = $HBoxContainer/SpeedGroup/Button_Pause
 	pause_btn.text = "继续" if TimeSystem.paused else "暂停"

src/UI/Panels/MainMenu/MainMenu.gd

@@ -1,26 +1,25 @@
+## 主菜单场景（挂载于 MainMenu.tscn）。
 extends Control
 
+## 点击"新游戏"：重置 GameState 后进入游戏世界。
 func MainMenu_NewGame_ButtonUp() -> void:
 	GameState.request_new_game()
 	get_tree().change_scene_to_file("res://src/Core/MainGame.tscn")
 
-
+## 点击"读取存档"：隐藏主按钮组并显示存档面板。
 func MainMenu_LoadGame_ButtonUp() -> void:
 	$ButtonGroup.hide()
 	$SavePanel.show()
-	pass # Replace with function body.
-
 
+## 点击"设置"（TODO：接入设置面板）。
 func MainMenu_Settings_ButtonUp() -> void:
-	pass # Replace with function body.
-
+	pass
 
+## 点击"退出"。
 func MainMenu_Quit_ButtonUp() -> void:
-	get_tree().quit();
-	pass # Replace with function body.
-
+	get_tree().quit()
 
+## 存档面板请求返回。
 func _on_save_panel_back_pressed() -> void:
 	$SavePanel.hide()
 	$ButtonGroup.show()
-	pass # Replace with function body.

src/UI/Panels/SavePanel.gd

@@ -1,8 +1,10 @@
+## 存档选择面板（挂载于 SavePanel.tscn）。
+## 显示存档列表与"新建存档"入口，通过信号通知外部结果。
 extends PanelContainer
 
+## 请求关闭面板（返回上级界面）。
 signal back_pressed
 
-
+## 点击"返回"按钮。
 func _on_button_esc_button_up() -> void:
 	back_pressed.emit()
-	pass # Replace with function body.

src/UI/Panels/SaveSlot.gd

@@ -1,5 +1,9 @@
+## 存档槽位条目（挂载于 SaveSlot.tscn）。
+## 展示单个存档信息；空槽位用于新建存档。
 extends PanelContainer
 
+## 槽位被点击时发出，save_id 为空表示点击了新建槽位。
+## @param save_id: 存档 ID
 signal slot_pressed(save_id: String)
 
 @onready var slot_index_label: Label = %SlotIndexLabel
@@ -9,9 +13,16 @@ signal slot_pressed(save_id: String)
 @onready var delete_button: Button = %DeleteButton
 @onready var arrow_button: Button = %ArrowIcon
 
+## 本槽位对应的存档 ID。
 var save_id: String = ""
+## 是否已有存档数据（false 表示新建槽位）。
 var has_data: bool = false
 
+## 填充为已有存档槽位。
+## @param id: 存档 ID
+## @param name_text: 存档名称
+## @param meta1: 第一行元数据
+## @param meta2: 第二行元数据
 func setup(id: String, name_text: String, meta1: String, meta2: String) -> void:
 	save_id = id
 	has_data = true
@@ -22,6 +33,7 @@ func setup(id: String, name_text: String, meta1: String, meta2: String) -> void:
 	delete_button.visible = true
 	arrow_button.visible = true
 
+## 填充为"新建存档"空槽位。
 func setup_empty() -> void:
 	has_data = false
 	slot_index_label.text = "+"
@@ -31,8 +43,10 @@ func setup_empty() -> void:
 	delete_button.visible = false
 	arrow_button.visible = false
 
+## 槽位本体被点击。
 func _on_pressed() -> void:
 	slot_pressed.emit(save_id)
 
+## 点击删除按钮（TODO：接入确认弹窗）。
 func _on_delete_button_button_up() -> void:
 	print("删除存档: ", save_id)