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

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

src/Core/GameState.gd

@@ -1,15 +1,21 @@
+## 全局游戏状态（Autoload 单例）。
+## 负责场景间参数传递与会话状态管理，不持有游戏内数据。
 extends Node
 
+## 进入游戏的方式。
 enum GameMode { NEW_GAME, LOAD_GAME }
 
+## 当前进入游戏的方式。
 var mode: GameMode = GameMode.NEW_GAME
+## 要加载的存档 ID（仅 LOAD_GAME 时有效）。
 var save_id: String = ""
 
-# 游戏内时间（12 月 × 30 天 = 360 天/年）
+# 游戏内时间（12 月 × 30 天 = 360 天/年），实际推进由 TimeSystem 负责
 var year: int = 1
 var month: int = 1
 var day: int = 1
 
+## 请求开始新游戏：重置模式与时间。
 func request_new_game() -> void:
 	mode = GameMode.NEW_GAME
 	save_id = ""
@@ -17,6 +23,8 @@ func request_new_game() -> void:
 	month = 1
 	day = 1
 
+## 请求加载指定存档。
+## @param id: 存档 ID
 func request_load_game(id: String) -> void:
 	mode = GameMode.LOAD_GAME
 	save_id = id

src/Core/MainGame.gd

@@ -1,11 +1,11 @@
+## 主游戏世界场景入口（挂载于 MainGame.tscn）。
+## 进入游戏时根据 GameState 模式初始化，并连接顶部 HUD 信号。
 extends Node
 
 func _ready() -> void:
 	TimeSystem.speed_index = Settings.default_speed_index
 	TimeSystem.speed = TimeSystem.SPEEDS[TimeSystem.speed_index]
-	pass
-
 
+## 顶部 HUD 的返回主菜单请求。
 func _on_top_bar_hud_sign_return_mainmenu() -> void:
 	get_tree().change_scene_to_file("res://src/UI/Panels/MainMenu/MainMenu.tscn")
-	pass # Replace with function body.

src/Core/Settings.gd

@@ -1,13 +1,20 @@
+## 用户设置（Autoload 单例）。
+## 负责个人偏好设置的持久化，保存于 user:// 目录，与游戏存档分离。
 extends Node
 
+## 设置文件的保存路径。
 const SAVE_PATH := "user://settings.cfg"
-var default_speed_index := 1   # 默认 5x
 
+## 新游戏开局时的默认流速档位索引（1 = 5x）。
+var default_speed_index := 1
+
+## 从磁盘加载设置（不存在则保持默认值）。
 func load_settings() -> void:
 	var cfg := ConfigFile.new()
 	if cfg.load(SAVE_PATH) == OK:
 		default_speed_index = cfg.get_value("time", "speed_index", 1)
 
+## 将当前设置写入磁盘。
 func save_settings() -> void:
 	var cfg := ConfigFile.new()
 	cfg.set_value("time", "speed_index", default_speed_index)

src/Core/TimeSystem.gd

@@ -1,21 +1,46 @@
+## 全局时间系统（Autoload 单例）。
+## 负责游戏时间的推进与播报，仅在世界场景中运行。
+## 历法：12 月 × 30 日 = 360 日/年。
 extends Node
 
-signal day_passed(year, month, day)
-signal month_passed(year, month)
-signal year_passed(year)
-signal speed_changed(speed_index)
-signal pause_changed(paused)
+## 每当推进一日后发出。
+## @param year: 当前年份
+## @param month: 当前月份（1-12）
+## @param day: 当前日（1-30）
+signal day_passed(year: int, month: int, day: int)
+## 每当进入新月份时发出（同一天内 day_passed 之后）。
+## @param year: 当前年份
+## @param month: 当前月份（1-12）
+signal month_passed(year: int, month: int)
+## 每当进入新年份时发出（同一天内 month_passed 之后）。
+## @param year: 当前年份
+signal year_passed(year: int)
+## 时间流速档位变化时发出。
+## @param speed_index: 新档位在 SPEEDS 中的索引
+signal speed_changed(speed_index: int)
+## 暂停状态变化时发出。
+## @param paused: 是否已暂停
+signal pause_changed(paused: bool)
 
+## 可选的时间流速倍率档位。
 const SPEEDS := [1.0, 5.0, 20.0]
+## 每月的天数。
 const DAYS_PER_MONTH := 30
+## 每年的月数。
 const MONTHS_PER_YEAR := 12
-
-var speed_index := 0
+## 现实世界每 1 天对应的时长（秒）。
 const DAY_LENGTH := 0.5
+
+## 当前流速档位在 SPEEDS 中的索引。
+var speed_index := 0
+## 当前流速倍率（与 SPEEDS[speed_index] 保持一致）。
 var speed := 1.0
+## 是否暂停时间推进。
 var paused := false
+## 已累积的现实时间（秒），未满 1 天。
 var _elapsed := 0.0
 
+
 func _process(delta: float) -> void:
 	if paused or not _is_in_game():
 		return
@@ -24,10 +49,14 @@ func _process(delta: float) -> void:
 		_elapsed -= DAY_LENGTH
 		_advance()
 
+
+## 判断当前场景是否为游戏世界场景（主菜单/存档界面不推进时间）。
 func _is_in_game() -> bool:
 	var scene := get_tree().current_scene
 	return scene != null and scene.name == "MainGame"
 
+
+## 推进一日并广播对应信号，跨月/跨年时补发 month_passed / year_passed。
 func _advance() -> void:
 	var new_month := false
 	var new_year := false
@@ -46,37 +75,58 @@ func _advance() -> void:
 	if new_year:
 		year_passed.emit(GameState.year)
 
+
+## 循环切换下一档流速，返回新倍率。
 func cycle_speed() -> float:
 	speed_index = (speed_index + 1) % SPEEDS.size()
 	speed = SPEEDS[speed_index]
 	speed_changed.emit(speed_index)
 	return speed
 
+
+## 直接设置流速档位（越界自动钳制）。
+## @param index: 目标档位索引
 func set_speed_index(index: int) -> void:
 	speed_index = clampi(index, 0, SPEEDS.size() - 1)
 	speed = SPEEDS[speed_index]
 	speed_changed.emit(speed_index)
 
+
+## 切换暂停状态，返回切换后的暂停状态。
 func toggle_pause() -> bool:
 	paused = not paused
 	pause_changed.emit(paused)
 	return paused
 
+
+## 显式设置暂停状态（幂等，状态未变化时不发信号）。
+## @param value: 目标暂停状态
 func set_paused(value: bool) -> void:
 	if paused == value:
 		return
 	paused = value
 	pause_changed.emit(paused)
 
+
+## 当前流速的显示文本，如 "x5"。
 func get_speed_label() -> String:
 	return "x%d" % int(speed)
 
+
+## 当前日期数组 [年, 月, 日]。
 func get_current_date() -> Array:
 	return [GameState.year, GameState.month, GameState.day]
 
+
+## 当前日期文本，如 "3年 5月 12日"。
 func get_date_text() -> String:
 	return "%d年 %d月 %d日" % [GameState.year, GameState.month, GameState.day]
 
+
+## 直接设置日期（供读档/测试使用）。
+## @param y: 年
+## @param m: 月（1-12）
+## @param d: 日（1-30）
 func set_date(y: int, m: int, d: int) -> void:
 	GameState.year = y
 	GameState.month = m

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)