模拟权杖 Simulated_Scepter 内核模块体系解析:module.ini 动态发现机制如何做到"零代码加功能"
模拟权杖 Simulated_Scepter 内核模块体系解析:module.ini 动态发现机制如何做到"零代码加功能"
🪄 本文为《崩坏:星穹铁道》自动化助手 模拟权杖(Simulated_Scepter) 的代码架构解析,带你快速看懂它的内核模块体系与 module.ini 动态发现机制:7 个功能内核如何通过 4 层继承复用公共能力,又如何在主界面一行注册代码都不写的情况下被自动发现、自动生成按钮。
先认识内核模块体系: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。
module.ini 动态发现:不导 Python,先读 INI
发现逻辑全部集中在 tool/registry.py 的 KernelRegistry,分三个阶段:
- 扫描声明:启动时遍历
core/*/module.ini,逐个用configparser解析成不可变的KernelSpec; - 静态校验:目录名必须是合法 Python 标识符、模块
id全局唯一、entry/factory/settings必须写成模块:符号的合法形式、带运行按钮的模块必须声明工厂函数; - 继承链检查:沿
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 呈现。
容错与测试:坏一个内核,只隔离一棵子树
这套机制的边界行为由 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 如何把声明变成控件——三个文件串起来,就是一条完整的"声明 → 发现 → 加载 → 呈现"链路 🎯。


