log_analysis.py 指标口径说明

试玩日志分析器（tools/log_analysis.py，Python 3 标准库单文件）的指标定义、自验对账记录与 AC 掷点批适配点。schema 事实源 = presentation/playtest_logger.gd。

用法

python log_analysis.py <jsonl 文件 | 目录 | 通配> [--per-run] [--rounds]

指标	定义
局数	run 行切出的局数（旧日志 = 文件数）。
通关率	`level_end.result == "victory"` 的局占比。
平均轮数/局	每局 `settlement` 快照数（=该局回合总数，快照每结算必发）。
进 Boss HP 均	快照反推法：Boss 首结算快照 HP ＋首轮承伤 − 首轮治疗。快照是回合末状态，用首轮回合内净额反推进场 HP，精确且自包含；仅统计到达 Boss 的局。
通关剩余 HP 均	通关局 `level_end.hp` 均值。
整局承伤均	每局全部敌方落地伤害之和的均值（见战斗级"承伤"）。

分组键 =（关卡，节点类型，节点深度）；battle 与 boss 分开输出。
承伤 = 该场全部 step 行中 source=enemy_action 且 type=damage 的 value 合计（即敌方攻击实际落地伤害；含"被减伤归零"的 0 值行）。
占生效 max_hp 比 = 承伤 ÷ 该场快照 hero.max_hp（"生效"指取快照实时值，非写死 50）。
承伤带判定：普通场 ≤20%、Boss 场 ≤50%，均值超带在"判定"列标 ✗。
battle_end 行由核心延迟发出（落在下一 node 行之后）且不带深度，本工具仅按 FIFO 对账其配对数（数据质量面），核心统计不依赖它——战斗上下文以 node 行开、相邻 node/局末收。

零承伤轮（窄口径，验收主指标）：本轮有敌方攻击落地（≥1 行 enemy_action×damage）且主角掉血为 0（该轮敌方落地伤害合计 = 0）。分母 = 有攻击落地的轮数。
- 蓄力拍（type=charge，含空拍/踩雷白喂）不计为"有攻击落地"——口径硬性排除。
- AC 批落地含"伤害下限 1"后，"被减伤归零"型轮将变为 1 点实伤，该值应趋零。
零掉血轮（宽口径，参考）：本轮主角 HP 不降（首回合按进场反推 HP 差分，其后按相邻快照差）。分母 = 敌战轮——"有过敌人的战斗"（任一轮出现敌人或攻击落地）的全部轮数。不能按单轮快照 enemies 判定：敌人当轮被歼的收尾轮快照 enemies 为空，但该轮仍属敌战（5678 局按单轮判定会得 4/7，按敌战轮才是 8/11）。

事实：settlement 快照在衰减段之后发出、且现有状态寿命全部为 1 结算 → 快照 buffs 字段恒为空（本次自验 7,473 个快照 0 非空）。禁止把快照 buffs 当战斗期状态使用。
复原口径：每结算的"轮窗口"= 上一 settlement 之后至本 settlement 之间的全部 step 行；窗口内 type=effect 的行按显示文本聚为增益键（增伤→attack_up、削弱→weaken、减伤→defend_up；未登记文本原样作键，如 4200 批浮现的失衡/暴走/乏力/敌方伏击+2 层），行数即层数。逐层数明细看 --rounds 流水的"增益复原"列。
快照 buffs 非空计数仍照常输出（当前恒 0），作为盲区持续暴露面：将来衰减时序改动若使快照变非空，这里会第一个显示出来。

激活条件：step 行出现候选掷点字段（ROLL/TIER/CRIT/AC_FIELD_CANDIDATES）。
字段存在 → 输出：d20 直方图、档位占比（缺口=AC−读数：达标=全额，1-3→×0.75， 4-7→×0.5，8+→×0.25；优先读落批直供的档位字段）、nat20 暴击率（理论 5% ±2pp 健康检查）、观察 EV 减免 vs 理论值（AC10 → 21.25%）、按攻击方向（主角→敌 / 敌→主角）分组。
字段不存在（AC 批前日志）→ 显示"不适用（AC 批前日志）"，其余指标照常。
落批适配入口（一行）：【数据质量】节的"step 行未知字段观测面"会自动列出全部新键及样例；把真实字段名补进 FIELD_CANDIDATES 常量即可，其余零改动。

任务背景称 step 行含分量字段 baseline/attach/normal/pierce/magic—— 现行日志（2026-09-16 schema）没有这些字段：_on_step_row 只落 kind/type/source/cell/round/text/value/highlight 八键。本工具的未知键观测面会在它们出现时自动捕获；届时按落批语义接入，不动 AC 批范围内文件。
掷点字段名以落批实际为准（候选名单只作探测，不作断言）。

局	人工对账	结果
5678（perfect 通关）	整关掉血合计 = 深度2 场 1 + 深度3 场 1 + Boss 场 4 = 6	工具输出 6 ✓
5678	零掉血轮宽口径：敌战 11 轮 − 掉血 3 轮 = 8/11	工具输出 8/11 ✓
5678	零承伤轮窄口径：被减伤归零型 3 轮（深度1 r1 / Boss r1 / Boss r4）	工具输出 3 ✓
1234（perfect 通关）	独立脚本计数：敌方伤害 12、治疗 8、11 轮（HP 守恒 50−12+8=50）	工具输出 12/11/终局 50 ✓
4200 批（233,254 行）	run 行 600、level_end 600（500 胜 100 败）	切 600 局，normal 66.7% + perfect 100% = 500 胜 ✓