机械之灵

一个可配置的日志分流与诊断助手，专为模组化 Minecraft 设计。

模组化 Minecraft 的日志可能令人望而生畏。一个无害的兼容性警告看起来可能像灾难，而真正重要的线程、配方或性能问题可能被淹没在数百条不相关的消息中。

MachineSpirit 会监视日志，并在发生值得注意的事件时添加有用的上下文。

它不会替换、隐藏或修改原始的警告或错误。相反，它会添加第二条消息，解释 MachineSpirit 对此的了解、是否匹配已知问题，并且在可能的情况下，指出服务器所有者或整合包作者应从何处开始调查。

并带有一丝机械神教认可的异端气息。

它能做什么？

MachineSpirit 可以：

• 识别已知的警告和错误，使用可配置的规则。
• 保留原始日志消息，以便开发者仍能获得真实的诊断信息。
• 检查异常堆栈跟踪，并识别最可能涉及的模组或库。
• 在证据充足时显示可能的原因指向和相关调用路径。
• 为服务器管理员提供一个故障排查的起点，而不是仅仅说“发生了错误”。
• 区分常见类别，如兼容性问题、线程/生命周期违规、配方/数据错误、缺失类、网络问题、内存故障和性能警告。
• 限制重复评论的频率，防止 MachineSpirit 成为新的日志垃圾来源。
• 将更详细的诊断信息保存在 logs/machinespirit-triage.log 中。
• 允许整合包作者为他们的包特有的问题创建自己的规则。
• 使用 /machinespirit reload 无需重启即可重载规则。
• 使用 /machinespirit test <level> 生成测试警告/错误。

示例

一条普通的模组化日志可能显示：

[ERROR] A mod is calling registerReloadListener at the wrong time.

MachineSpirit 可以添加如下上下文：

[MachineSpirit] Actual thread heresy detected.
ModernFix is containing it.
[MachineSpirit] Cause pointer:
likely source ProjectRed Integration;
call path also includes CodeChickenLib.
Server operator: start there, preserve the original stack trace,
and retest after any version/config change.
Attribution is probable, not proven.

MachineSpirit 执行诊断分流。堆栈跟踪可以显示涉及了哪些模组，但不能证明哪一个最终负责。MachineSpirit 刻意使用诸如 “可能来源”之类的措辞，而不是错误地宣布某个模组有罪。

已知问题与未知问题

MachineSpirit 有两层分析。

已知问题可以拥有精心编写的规则和具体的解释。这些是最高置信度的响应，非常适合具有已知兼容性怪癖的整合包。

对于其他错误，MachineSpirit 可以检查可用证据（如异常类型、日志记录器、线程和堆栈跟踪），以提供谨慎的初步分类，并将操作员指向最相关的代码或模组。

它是基于规则且确定性的。MachineSpirit 不是 AI 聊天机器人，也不会将你的日志发送到某个地方进行猜测。

对于整合包作者

这个模组的主要目标之一是允许包作者将他们原本需要反复解释的知识编码下来。

如果你的包有意产生一个看起来吓人但已被理解的警告，MachineSpirit 可以解释它。

如果某个特定消息意味着玩家应该报告问题，MachineSpirit 可以说出来。

如果一个警告意味着服务器应立即进行性能剖析，MachineSpirit 也可以说。

规则可以通过以下文件自定义：

config/machinespirit-rules.json

这允许同一个诊断引擎根据其安装所在的整合包而表现不同。

对于服务器所有者

MachineSpirit 旨在让日志对实际运营服务器的人更有用。

而不是这样：

ERROR
[large stack trace]

目标是更接近这样：

ERROR
[original stack trace]
MachineSpirit:
Likely subsystem: threading
Likely source: Mod A
Call path also contains: Library B
Start your investigation here.
Keep the original stack trace when reporting the problem.

它不会自动修复损坏的模组、消除不兼容，或替代适当的性能剖析和调试工具。

它会尝试让故障排查的最初几分钟少一些痛苦。

个性

MachineSpirit 的诊断被刻意包裹在一种过度戏剧化的机器崇拜个性中。

可以期待诸如 heresy、Magos之类的词语，以及偶尔对你 JVM 精神状态表达的关切。

在那之下是一个严肃的诊断工具。

如果 Minecraft 报告：

Can't keep up!

MachineSpirit 可能会回应：

THE MACHINE SPIRIT IS ACTUALLY SUFFERING.
Check MSPT and profile this workload.

MachineSpirit 处于早期开发阶段，因此功能、规则、输出格式和行为可能会在版本之间变化。虽然它旨在保留原始日志消息并避免干扰正常操作，但请报告任何错误的分类、崩溃或意外行为。