故障排查

先确认失败发生在哪一步：安装、加载配置、读取输入、计算、读取结果或发布。保留完整异常链；CLI默认文字报告便于定位，validate/explain --format json用于程序读取。以下处理不会要求修改原始日志或覆盖既有结果。

Python调用：按失败阶段处理

PlanValidationError.diagnostics包含本次可确认的错误，单错也是一项；blocked_checks说明因无效依赖暂未检查的部分。每项同时保存path、message、code。path是配置字段位置，source是文件路径；二者不可混用。只打印$.batch_version不够判断问题，应保留message中的实际约束及code，存在时再展示行列与hint。

from chronaxis import load_analysis_plan, PlanValidationError
try:
    plan = load_analysis_plan("analysis.yaml")
except PlanValidationError as error:
    for item in error.diagnostics:
        print(item.source, item.path, item.code, item.message, item.hint)
    print(error.blocked_checks)
    raise  # 保留原始异常链；不要把加载失败当成空计划继续运行

下面的片段接前面的plan加载代码。捕获运行或发布异常后，通过exc.__cause__读取被包装的原始异常；直接抛出的错误可能没有包装原因，此时为None。AnalysisError没有承诺名为cause或diagnostics的统一属性，详见AnalysisRunner异常说明。

from chronaxis import AnalysisRunner, AnalysisError

try:
    with AnalysisRunner().run(plan) as result:
        result.write("results")
except AnalysisError as exc:
    print(type(exc).__name__, str(exc))
    if exc.__cause__ is not None:
        print(type(exc.__cause__).__name__, str(exc.__cause__))
    raise  # 保留异常链，不把失败当作空结果

KeyboardInterrupt/SystemExit表示取消，不应作为成功返回。异常链上的runner_cleanup_owner或analysis_result_cleanup_owner只在失败清理未完成时出现；检查属性存在后才调用其close，不假定每个错误都有这些属性。

环境与配置

计算项缺少operation时，先补计算方法。程序明确方法后才检查该方法需要的字段，不会要求你补其他方法才使用的rule、window或q。其他独立字段的错误仍会一并报告。

condition_duration缺少duration_comparison时，请按业务选择：">="包含恰好达到门槛的活动，">"要求严格超过。

文件、时间与解码

结果为空或不完整

资源与发布

需要保留现场时，在下一次复现配置中设置diagnostics.retain_work: true；需要输入位置时再单独开启trace。记录配置、命令、错误链、运行清单和可共享的最小合成输入，以便重现。

高性能积分器的会话失败

fast run的任一分卷失败都会终止本次会话，不发布正常成功汇总。先用fast validate或fast explain检查配置；它们不代替实际读取验证。

字段默认值、可运行配置和状态解释见高性能积分器。