docs: 全局脚本补充文档注释（14 个文件 29 处）

src/Character/CultivationManager.gd

@@ -8,6 +8,7 @@ signal realm_changed(d: Disciple)
 signal cultivation_log(text: String)
 
 
+## 挂接每日推进信号。
 func _ready() -> void:
 	# 每日推进时结算全体已入宗弟子的修为与境界
 	TimeSystem.day_passed.connect(_on_day_passed)

src/Character/Disciple.gd

@@ -20,7 +20,7 @@ const REALM_NAMES: Array[String] = ["练气", "筑基", "金丹", "元婴", "化
 var id: int = 0                # 唯一编号（DiscipleManager 分配）
 var name: String = ""
 var age: int = 0
-var aptitude: Aptitude = Aptitude.ORDINARY
+var aptitude: Aptitude = Aptitude.ORDINARY   # 资质（入宗分流结果）
 var roots: Array[SpiritRoot] = []   # 普通弟子 1~5 根；天灵根固定 1 根
 var is_heavenly: bool = false       # 天灵根标记（仅天骄资质，概率见配置）
 var join_year: int = 0              # 入宗年份（0 = 未入宗/候选），accept 时快照
@@ -35,6 +35,7 @@ var hunger_days: int = 0            # 断粮累计天数（≥阈值离宗，方
 func get_aptitude_name() -> String:
 	return APTITUDE_NAMES[aptitude]
 
+## 灵根显示文本，如 "金、木"。
 func get_roots_text() -> String:
 	var names: Array[String] = []
 	for root in roots:
@@ -49,6 +50,7 @@ func get_root_count_capacity() -> float:
 		return 0.0
 	return 1.0 / roots.size()
 
+## 境界显示文本，如 "练气5层"、"筑基初期"。
 func get_realm_text() -> String:
 	if realm_index == 0:
 		return "%s%d层" % [REALM_NAMES[realm_index], sub_realm_index + 1]

src/Character/DiscipleManager.gd

@@ -35,6 +35,7 @@ var _days_until_recruit := 0
 var _next_id := 1
 
 
+## 挂接每日推进信号并初始化招募倒计时。
 func _ready() -> void:
 	# 挂到时间系统上：每日推进时倒计时，满间隔生成候选并暂停时间
 	TimeSystem.day_passed.connect(_on_day_passed)

src/Core/GameConfig.gd

@@ -72,6 +72,7 @@ var aptitude_weights_by_difficulty: Dictionary = {
 }
 
 
+## 启动时加载配置文件。
 func _ready() -> void:
 	_load_config()
 

src/Core/GameState.gd

@@ -13,9 +13,9 @@ var profile_id: int = 0
 var save_slot: String = ""
 
 # 游戏内时间（12 月 × 30 天 = 360 天/年），实际推进由 TimeSystem 负责
-var year: int = 1
-var month: int = 1
-var day: int = 1
+var year: int = 1   # 年
+var month: int = 1  # 月（1-12）
+var day: int = 1    # 日（1-30）
 
 ## 请求开始新游戏。
 ## @param pid: 新存档组 ID（主菜单创建）

src/Core/MainGame.gd

@@ -2,6 +2,7 @@
 ## 进入游戏时根据 GameState 模式初始化，并连接顶部 HUD 信号。
 extends Node
 
+## 进入游戏世界：注册场景分组，按 GameState 模式初始化（新游戏/读档）。
 func _ready() -> void:
 	# 注册为游戏世界场景（供 TimeSystem 判断是否推进时间）
 	add_to_group("game_scene")

src/Core/SectManager.gd

@@ -10,40 +10,58 @@ var reputation := 0         # 声望
 var food := 0               # 灵米（食物资源，HUD 显示"灵米"）
 
 
+## 增加灵石并广播信号。
+## @param amount: 增加量
 func add_spirit_stones(amount: int) -> void:
 	spirit_stones += amount
 	emit_signal("spirit_stones_changed", spirit_stones, amount)
 
+## 减少灵石并广播信号。
+## @param amount: 减少量
 func remove_spirit_stones(amount: int) -> void:
 	spirit_stones -= amount
 	emit_signal("spirit_stones_changed", spirit_stones, -amount)
 
+## 增加声望并广播信号。
+## @param amount: 增加量
 func add_reputation(amount: int) -> void:
 	reputation += amount
 	emit_signal("reputation_changed", reputation, amount)
 
+## 减少声望并广播信号。
+## @param amount: 减少量
 func remove_reputation(amount: int) -> void:
 	reputation -= amount
 	emit_signal("reputation_changed", reputation, -amount)
 
+## 增加灵米并广播信号。
+## @param amount: 增加量
 func add_food(amount: int) -> void:
 	food += amount
 	emit_signal("food_changed", food, amount)
 
+## 减少灵米并广播信号。
+## @param amount: 减少量
 func remove_food(amount: int) -> void:
 	food -= amount
 	emit_signal("food_changed", food, -amount)
 
+## 直接设定灵石（读档/新游戏用，带信号 HUD 自动刷新）。
+## @param value: 目标值
 func set_spirit_stones(value: int) -> void:
 	var delta := value - spirit_stones
 	spirit_stones = value
 	spirit_stones_changed.emit(spirit_stones, delta)
 
+## 直接设定声望（读档/新游戏用，带信号 HUD 自动刷新）。
+## @param value: 目标值
 func set_reputation(value: int) -> void:
 	var delta := value - reputation
 	reputation = value
 	reputation_changed.emit(reputation, delta)
 
+## 直接设定灵米（读档/新游戏用，带信号 HUD 自动刷新）。
+## @param value: 目标值
 func set_food(value: int) -> void:
 	var delta := value - food
 	food = value

src/Core/TimeSystem.gd

@@ -41,6 +41,7 @@ var paused := false
 var _elapsed := 0.0
 
 
+## 每帧累积时间，满一天推进日期（仅游戏世界场景内）。
 func _process(delta: float) -> void:
 	if paused or not _is_in_game():
 		return

src/Sect/BuildingManager.gd

@@ -10,6 +10,7 @@ signal buildings_changed
 var buildings: Array[Building] = []
 
 
+## 挂接每日推进信号，结算建筑产出。
 func _ready() -> void:
 	# 每日推进时结算各建筑产出
 	TimeSystem.day_passed.connect(_on_day_passed)

src/UI/HUD/top_bar_hud.gd

@@ -19,6 +19,7 @@ signal sign_open_save
 @onready var pause_button: Button = %Button_Pause
 @onready var speed_buttons: Array[Button] = [%Button_Speed1, %Button_Speed5, %Button_Speed20]
 
+## 初始化：连接速度按钮与各信号、设置初始显示、应用配置字号。
 func _ready() -> void:
 	for i in speed_buttons.size():
 		var btn := speed_buttons[i]

src/UI/Panels/BuildingsPanel/buildings_panel.gd

@@ -10,6 +10,7 @@ extends Control
 var _was_paused := false
 
 
+## 订阅建筑变化信号，默认隐藏。
 func _ready() -> void:
 	BuildingManager.buildings_changed.connect(_on_buildings_changed)
 	visible = false

src/UI/Panels/DisciplesPanel/disciple_detail_panel.gd

@@ -7,6 +7,7 @@ extends Control
 @onready var info_label: Label = %InfoLabel
 
 
+## 默认隐藏。
 func _ready() -> void:
 	visible = false
 

src/UI/Panels/DisciplesPanel/disciples_panel.gd

@@ -18,6 +18,7 @@ const APTITUDE_COLORS := {
 var _was_paused := false
 
 
+## 订阅名录变化信号，默认隐藏。
 func _ready() -> void:
 	# 名录变化时刷新（面板打开期间也同步）
 	DiscipleManager.disciples_changed.connect(_on_disciples_changed)

src/UI/Panels/RecruitPanel/recruit_panel.gd

@@ -18,6 +18,7 @@ var _check_buttons: Array[CheckButton] = []
 var _entry_disciples: Array[Disciple] = []
 
 
+## 订阅候选生成信号，默认隐藏。
 func _ready() -> void:
 	# 订阅候选生成信号：开局与定期招募都会触发
 	DiscipleManager.applicants_generated.connect(_on_applicants_generated)