游戏 AI / 系统课时
给阶段切换加哪些调试日志
给阶段切换加哪些调试日志
阶段切换一旦出现误触发、漏触发或来回抖动,只看最终阶段通常无法定位原因。有效日志应在一次转移中同时记录当前阶段、触发事实、目标、关键数值、规则和最终结果,让一次异常决策能够被单条日志还原。
学习目标
- 设计一条完整的阶段切换诊断日志
- 区分触发条件、候选阶段和最终结果
- 用结构化字段快速定位误触发、漏触发和重复切换
一条阶段日志至少要回答什么
一条可用的 phase transition 日志,最少要回答“谁在什么时候从哪里去了哪里、为什么去”。因此推荐固定记录 bossId、battleId、fromPhase、toPhase、reason、healthRatio、targetId、phaseTimer,以及规则命中情况。
其中 reason 不应只写成“hp low”,而应带上可识别的规则名称,例如 health_threshold、shield_broken 或 phase_timer_expired。这样搜索日志时可以直接按触发来源聚合,而不必猜具体实现。

用结构化日志记录一次完整转移
调试日志最好使用结构化对象,而不是把所有字段拼成一条自然语言字符串。这样可以直接送入日志平台,并按 fromPhase、toPhase、reason 或 battleId 查询同一场战斗。
下面的 Python 示例演示最小日志记录器。它不依赖第三方库,可以直接运行验证字段和输出结构。
import json
from datetime import datetime, timezone
def log_phase_transition(
boss_id: str,
battle_id: str,
from_phase: str,
to_phase: str,
reason: str,
health_ratio: float,
target_id: str | None,
phase_timer: float,
matched_rule: str,
) -> None:
event = {
"event": "boss_phase_transition",
"timestamp": datetime.now(timezone.utc).isoformat(),
"bossId": boss_id,
"battleId": battle_id,
"fromPhase": from_phase,
"toPhase": to_phase,
"reason": reason,
"healthRatio": health_ratio,
"targetId": target_id,
"phaseTimer": phase_timer,
"matchedRule": matched_rule,
}
print(json.dumps(event, ensure_ascii=False))
log_phase_transition(
boss_id="boss-01",
battle_id="battle-<ID>",
from_phase="phase_1",
to_phase="phase_2",
reason="health_threshold",
health_ratio=0.39,
target_id="player-7",
phase_timer=52.4,
matched_rule="hp<=0.40",
)预期输出
{"event": "boss_phase_transition", "timestamp": "<TIME>", "bossId": "boss-01", "battleId": "battle-<ID>", "fromPhase": "phase_1", "toPhase": "phase_2", "reason": "health_threshold", "healthRatio": 0.39, "targetId": "player-7", "phaseTimer": 52.4, "matchedRule": "hp<=0.40"}timestamp 会因实际运行时间不同而变化,因此使用 <TIME> 表示动态值。生产实现中还可以加入 stateVersion、decisionId 或 transitionId,用于关联同一次评估中的多条日志,但字段应保持稳定,不要每个版本随意改名。
把“为什么没有切换”也记录下来
只记录成功转移仍不足以排查漏触发。更有价值的是在候选规则被拒绝时留下简洁原因,例如当前阶段不允许迁移、HP 未达到阈值、事件已经消费、目标条件不满足或转场锁仍未释放。
排查时可以把日志分成三层:输入事实、规则判断、结果状态。输入事实说明系统看到了什么;规则判断说明为什么接受或拒绝;结果状态说明最终是否真的改变。三层齐全后,误触发和漏触发通常都能在同一次 battleId 查询中还原。
避免日志反过来制造噪声
阶段评估可能每帧执行,因此不能每次轮询都打印完整对象。建议只在候选条件变化、规则命中、阶段切换或异常拒绝时记录详细日志;高频稳定状态可以降低到 trace 级别,正式环境只保留 info 或 warning 级别的关键事件。
对于同一场战斗,最好始终带上 battleId,并在阶段日志里同时输出 fromPhase 和 toPhase。发现 phase_2 -> phase_1 这种不符合设计的迁移时,可以立即追溯是哪条规则触发,而不是从大量普通战斗循环日志里人工猜测。
阶段日志真正的价值不是“留下更多文字”,而是让每次状态迁移都具备可复盘的上下文。只要输入事实、命中规则和最终转移结果能够在日志中一一对应,调试就会从猜测变成定位。