游戏 AI / 系统课时

给阶段切换加哪些调试日志

给阶段切换加哪些调试日志

阶段切换一旦出现误触发、漏触发或来回抖动,只看最终阶段通常无法定位原因。有效日志应在一次转移中同时记录当前阶段、触发事实、目标、关键数值、规则和最终结果,让一次异常决策能够被单条日志还原。

学习目标

  • 设计一条完整的阶段切换诊断日志
  • 区分触发条件、候选阶段和最终结果
  • 用结构化字段快速定位误触发、漏触发和重复切换

一条阶段日志至少要回答什么

一条可用的 phase transition 日志,最少要回答“谁在什么时候从哪里去了哪里、为什么去”。因此推荐固定记录 bossId、battleId、fromPhase、toPhase、reason、healthRatio、targetId、phaseTimer,以及规则命中情况。

其中 reason 不应只写成“hp low”,而应带上可识别的规则名称,例如 health_threshold、shield_broken 或 phase_timer_expired。这样搜索日志时可以直接按触发来源聚合,而不必猜具体实现。

Boss 阶段切换调试日志的上下文与排查链路

用结构化日志记录一次完整转移

调试日志最好使用结构化对象,而不是把所有字段拼成一条自然语言字符串。这样可以直接送入日志平台,并按 fromPhase、toPhase、reason 或 battleId 查询同一场战斗。

下面的 Python 示例演示最小日志记录器。它不依赖第三方库,可以直接运行验证字段和输出结构。

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",
)

预期输出

text
{"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 这种不符合设计的迁移时,可以立即追溯是哪条规则触发,而不是从大量普通战斗循环日志里人工猜测。

阶段日志真正的价值不是“留下更多文字”,而是让每次状态迁移都具备可复盘的上下文。只要输入事实、命中规则和最终转移结果能够在日志中一一对应,调试就会从猜测变成定位。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

给阶段切换加哪些调试日志

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通