simulation-failure-triage

模拟失败分诊

目标

对常见的模拟失败特征进行分类，并提供即时操作、重试阶梯和停止条件。

要求

• Python 3.10+
• 无外部依赖
• 适用于 Linux、macOS 和 Windows

需要收集的输入

输入	描述	示例
代码	模拟代码	LAMMPS、VASP、MOOSE、QE
阶段	设置、运行时、后处理	runtime
症状	失败迹象	nan,pressure-blowup
日志文本或文件	错误证据	Lost atoms、ZBRENT
最近的更改	最近修改的设置	larger timestep

判定指南

• 首先保留证据：日志、输入文件、可执行文件版本和调度器输出。
• 区分设置错误、数值不稳定和物理模型问题。
• 每次仅通过一项受控更改进行重试。
• 当结果失去科学意义，或缺少必需的模型输入时，停止重试。

脚本输出

scripts/failure_triage.py 会输出：

• likely_causes
• immediate_actions
• retry_ladder
• stop_conditions
• evidence

工作流

python3 skills/robustness/simulation-failure-triage/scripts/failure_triage.py \
  --code LAMMPS \
  --stage runtime \
  --symptoms nan,pressure-blowup \
  --recent-change "increased timestep" \
  --json

错误处理

阶段无效或日志文件过大时，程序会以退出代码 2 终止。未知症状会作为自定义证据保留。

局限性

此技能提供初步分诊，但不保证能够修复失败的模拟。

验证清单

• 在任何重新运行之前，记录保留的证据集：复制日志、输入文件、调度器输出以及可执行文件/版本字符串（依据第一项 immediate_actions），以便复现原始故障。
• 引用了本次运行中的第一条警告/错误，而不只是最后的崩溃行，并确认 evidence.log_excerpt（前 500 个字符，保留原始大小写）包含该内容；如果摘录未包含根本特征，则使用 --log-file/--log-text 重新运行。
• 记录每一项 likely_causes 的 symptom、category 和 first_action，并确认没有真正的特征因关键字缺失于 LOG_HINTS/PATTERNS 而被归入 category: custom。
• 确认故障类别正确，未被错误标记：段错误/SIGSEGV/信号 11/core-dumped 应归为 crash（而不是 corrupted-output）；OOM/bad_alloc/oom-kill 应归为 out-of-memory（而不是 incomplete-run）。
• 严格按照 retry_ladder 每次只做一项更改，并记录每一级更改的单一参数及其影响（内存受限时也包括内存这一级）。
• 检查每一项 stop_conditions，一旦满足任一条件（例如势函数/赝势无法验证，或结果取决于任意的稳定化设置），就停止重试，而不是叠加任意的稳定化调整。
• 任何数值问题恢复后，都交由 simulation-validator 技能检查守恒性、物理边界和“结果是否可信”，而不是在此处直接宣布成功。

常见陷阱与合理化说辞

诱人的捷径	为什么这是错的／应该怎么做
“日志的最后一行就是错误，所以我会修复它。”	最后的崩溃行通常只是下游症状；脚本的第二个 immediate_actions 条目之所以存在，是因为第一个警告／错误才是真正原因。将其记录在 evidence.log_excerpt 中，并从那里开始分类处理。
“它发生了段错误，所以是输出损坏／磁盘问题。”	crash（SIGSEGV／signal 11／core dumped）属于内存故障类别，指向越界、空指针或 ABI 错误，需要使用 gdb／valgrind／ASan 复现——而不是 I/O 问题。不要将其视为 corrupted-output。
“作业被杀掉了，所以我只要增加 walltime 就行。”	单凭 killed 确实无法确定原因，应归为 incomplete-run；OOM 特征（bad_alloc、oom-kill、“out of memory”）则是独立的 out-of-memory 原因，需要减少内存使用／增加 --mem，而不是增加 walltime。
“我会同时降低 dt、更改预条件器并调整 barostat，让它运行起来。”	重试阶梯要求每一阶只进行一项受控更改；堆叠修复会让结果“取决于任意的稳定性调整”，这会明确触发 stop_conditions。每次更改一个参数，记录其影响，然后再继续。
“我添加了缺失的 PAIR coeff 路径，程序也运行了，所以物理模型没问题。”	修复 missing-potential／bad-pseudopotential 后顺利运行，只能解决配置问题，不能证明结果有效；物种映射、价电子数或泛函仍可能有误。运行完成不等于结果正确。
“现在能运行了，故障分类也完成了。”	故障分类只能恢复执行。守恒性、物理边界和收敛性不在此处的处理范围内——在相信任何数值之前，请交由 simulation-validator 验证。

安全性

输入验证

• --stage 会根据固定的允许列表（setup、runtime、postprocess、unknown）进行检查；其他任何值都会以代码 2 退出。
• --code 必须非空且不超过 100 个字符；值为空或过长都会以代码 2 退出。
• --symptoms 会按逗号拆分，最多允许 50 项，每项最多 100 个字符；超过任一限制都会以代码 2 退出。
• 不会拒绝未知症状；它们会作为 custom 证据保留，而不会被悄悄丢弃。
• 没有数值参数，因此不适用有限值／正值检查。
• 所有输入验证失败（以及日志读取错误）都会被捕获，并以代码 2 退出，同时输出 stderr 消息。

文件访问

• 唯一读取的文件是可选的 --log-file 路径；未提供时，脚本不会读取任何文件。
• 读取前，会通过 stat 检查日志文件大小；如果超过 10 MB 上限（MAX_LOG_SIZE），脚本会引发错误并以代码 2 退出。文件内容和 --log-text 随后都会截断至 10 MB。
• 脚本不会写入任何文件；所有结果都输出到 stdout（使用 --json 时为 JSON，否则为纯文本）。
• 路径沙箱限制：日志路径不受工作目录限制，因此脚本可以读取调用进程有权限读取的任何文件；只能传入可信路径。

工具限制

• allowed-tools 为 Read, Bash, Write, Grep, Glob。
• Bash 只运行随附的 scripts/failure_triage.py。
• Read 用于打开技能自身的文件和用户提供的日志，以检查故障证据；Grep／Glob 用于定位日志文件、输入和先前输出；Write 根据用户指示记录分类笔记或保存的证据。随附脚本本身不会写入文件。

安全措施

• 不使用 eval／exec，也不执行动态代码；日志文本仅作为数据处理，绝不会运行。
• 脚本不会启动子进程，也不会运行外部求解器。
• 输出为结构化 JSON（--json），便于机器检查。
• DoS 限制可约束资源使用：日志大小／文本上限为 10 MB，症状最多 50 项，code 和每项症状的长度上限均为 100 个字符。

参考资料

• 常见故障特征和重试阶梯见 references/failure_patterns.md。

版本历史

• 1.1.3：添加 Verification checklist（基于证据、与 failure_triage.py 输出关联的检查——保留证据集、首个错误摘录、类别误标防护、单项变更重试阶梯、停止条件、移交 simulation-validator），并添加 Common pitfalls & rationalizations 表格，涵盖仅根据最后一行进行分类、将段错误当作 I/O、混淆内存不足与超时、叠加多项稳定性改动，以及“程序运行了，所以结果有效”。
• 1.1.1：强化评估，使其具有区分度——每个用例现在都通过 script_checks 固定 failure_triage.py 的确切 JSON 输出（具体的 category／first_action 字符串、基于日志提示推断症状、固定的重试阶梯／停止条件文本、近期变更的即时操作），因此测试套件衡量的是该技能的实际输出，而不是通用的故障分类知识。
• 1.1.0：添加专门的 out-of-memory 和 crash（段错误）分类；不再将段错误和内存不足错误误标为 I/O 或执行中断。保留原始用例的日志摘录。添加输入验证上限（症状、代码长度）。改进描述，将深入验证交由 simulation-validator 处理。修复 missing-potential 评估令牌。
• 1.0.0：初始的跨代码模拟故障分类技能。