模拟权杖 Simulated_Scepter 内核模块体系解析:module.ini 动态发现机制如何做到"零代码加功能"

原创2026-10-28 17:45:021,332 阅读

模拟权杖 Simulated_Scepter 内核模块体系解析:module.ini 动态发现机制如何做到"零代码加功能"

🪄 本文为《崩坏:星穹铁道》自动化助手 模拟权杖(Simulated_Scepter) 的代码架构解析,带你快速看懂它的内核模块体系与 module.ini 动态发现机制:7 个功能内核如何通过 4 层继承复用公共能力,又如何在主界面一行注册代码都不写的情况下被自动发现、自动生成按钮。

模拟宇宙寰宇蝗灾界面,对应 Simulated/AnyFate 内核的运行对象

先认识内核模块体系:core/ 下的插件家族

core/ 目录下有 7 个内核模块,每个都是一个标准 Python 包,且文件约定完全一致:

约定文件 职责
engine.py 主引擎类 + 工厂函数 create_engine()
settings_ui.py 该内核专属的配置对话框
config/default.json 默认配置,首次运行时复制到用户目录
module.ini 模块"身份证",动态发现机制的入口
actions/*.json JSON 动作脚本,驱动状态机

以 core/simulated/module.ini 为例,这份 INI 声明了模块的身份、继承关系与所有入口点:

[module]
id = Simulated
description = 模拟宇宙
parent = Common
entry = engine:SimulatedUniverse
factory = engine:create_engine
settings = settings_ui:SettingsDialog
order = 10
button = 运行模拟宇宙
button_order = 10
calibration = true

[config]
file = core_settings/simulated.json
default = config/default.json

一张继承树:7 个内核如何复用 4 层通用能力

parent 字段把 7 个内核组织成一棵继承树(括号内为 engine.py 中的引擎类):

Common        通用状态机 + JSON 脚本执行
├── Simulated   模拟宇宙 / 寰宇蝗灾
│   └── AnyFate 任意命途(通用寻路、骰子、事件流程)
│       ├── IronBlood  铁血战士
│       └── FingerSnap 弹指一挥(倒计时推演)
│   └── Currency  货币战争
└── Divergent  差分宇宙
内核目录 功能 继承自 运行按钮
core/simulated/ 模拟宇宙 · 寰宇蝗灾 Common 运行模拟宇宙
core/any_fate/ 寰宇命途(任意命途演算) Simulated 一般寰宇命途演算(毁灭原动力)
core/iron_blood/ 铁血战士 AnyFate 擢升铁血战士
core/finger_snap/ 弹指一挥 AnyFate 无按钮
core/currency/ 货币战争 Common 货币战争自动收集
core/divergent/ 差分宇宙 Common 无按钮
core/common/ 通用 JSON 脚本运行器 无 无按钮

底层是 core/common/engine.py 中的 StateKernel 状态机:按 JSON 脚本顺序匹配屏幕触发条件(图像/文本/状态),命中即执行动作。上层内核只需继承并覆写差异逻辑,例如 AnyFateUniverse 继承 SimulatedUniverse 补充"任意命途"选择,FingerSnap 再继承它专注倒计时推演,见 core/finger_snap/engine.py#L47。

弹指一挥模块的倒计时 DP 推演地图,展示模块间复用的寻路与推演能力

module.ini 动态发现:不导 Python,先读 INI

发现逻辑全部集中在 tool/registry.py 的 KernelRegistry,分三个阶段:

  1. 扫描声明:启动时遍历 core/*/module.ini,逐个用 configparser 解析成不可变的 KernelSpec;
  2. 静态校验:目录名必须是合法 Python 标识符、模块 id 全局唯一、entry/factory/settings 必须写成 模块:符号 的合法形式、带运行按钮的模块必须声明工厂函数;
  3. 继承链检查:沿 parent 向上验证——父内核必须存在、不允许循环继承、重复 id 会让相关子树整体失效。

关键设计:发现阶段只读 INI,绝不 import 任何模块的 Python 代码(tool/registry.py#L40-L83)。即使某目录的 INI 损坏或继承链断裂,也只会把它自己记入 errors 隔离掉,其余内核照常可用——这是"一个坏插件不拖垮整个宿主"的故障隔离设计。

运行时按需加载:入口、工厂与契约校验

只有用户真正点击时,注册表才加载对应代码:

  • load_class() 按 entry 导入引擎类,并断言它确实是父内核的子类(INI 声明的继承与 Python 类必须一致);
  • create_engine() 调用 factory 工厂函数实例化引擎,并做 isinstance 类型校验(tool/registry.py#L98-L114);
  • create_settings() 按 settings 字段动态创建该内核的配置对话框。

主界面 new_gui.py 只维护一个按钮容器:init_kernel_buttons 遍历 registry.runnable(),按 button_order 排序后为每个声明了 button 的内核动态生成"运行按钮 + ⚙️ 配置齿轮";下拉框、校准按钮、定时调度也基于同一份声明。order 决定排序、button 决定按钮文案、tray 决定是否常驻托盘——模块作者不改一行前端代码,就能控制自己的 UI 呈现。

模拟宇宙模块运行时的智能择路界面,由 JSON 动作脚本驱动状态机

容错与测试:坏一个内核,只隔离一棵子树

这套机制的边界行为由 test/test_core_registry.py 系统性覆盖:

  • 移走叶子模块后,兄弟模块加载不受影响(test_removing_leaf_does_not_affect_sibling_loading);
  • 缺少父内核时,仅该子树被禁用,独立模块正常(test_missing_parent_disables_descendants...);
  • 循环继承与损坏的 INI 被报告为错误,但不阻塞其他模块;
  • INI 继承与 Python 类不一致、工厂返回错误类型,都会抛出明确异常。

GUI 启动时也会把每个 registry.errors 逐条写入日志(new_gui.py#L622-L624),方便定位是哪个模块"缺席"了。

如何新增一个内核:3 个文件搞定

想给模拟权杖加一个新玩法?按约定新建 core/xxx/ 目录即可,主界面会自动发现:

[module]
id = Xyz
description = 新玩法
parent = Common
entry = engine:XyzKernel
factory = engine:create_engine
settings = settings_ui:SettingsDialog
button = 运行新玩法
button_order = 90

[config]
file = core_settings/xyz.json
default = config/default.json

再提供 engine.py(引擎类 + create_engine())、settings_ui.py 和 config/default.json,重启后按钮就出现在主界面。test/test_core_registry.py#L101-L107 中的 test_new_module_adds_entry_without_frontend_change 直接验证了这个承诺:"新增模块即出现入口,无需修改前端"。

架构小结:这套设计好在哪

  • 纯声明式注册:module.ini 是唯一事实来源,注册表、按钮、配置界面、脚本下拉框全部由它派生,不存在"代码改了、UI 忘更新"的问题;
  • 发现与加载分离:发现只解析 INI,加载延迟到用户操作,坏模块的导入错误不会在启动时炸出来;
  • 契约校验:INI 继承链 ↔ Python 类继承、工厂 ↔ 返回类型,双重把关,防止元数据与代码漂移;
  • 故障隔离:校验错误按内核维度隔离,宿主界面永远可用;
  • UI 自主权:order / button_order / tray / calibration 字段让模块作者完全掌控自己的呈现方式。

建议学习路径:先通读 tool/registry.py 的 KernelSpec 与 KernelRegistry,再对照 core/common/engine.py 的 StateKernel 状态机,最后看 new_gui.py 的 init_kernel_buttons 如何把声明变成控件——三个文件串起来,就是一条完整的"声明 → 发现 → 加载 → 呈现"链路 🎯。

登录后查看全文
Simulated_Scepter