Mod 加载¶
职责¶
mod_manager 发现 MOD_INFO、构建依赖图、选择可用/默认 Mod、记录各 world 的有序
active list、应用声明的 Mod migration/removal，并向数据 loader 提供有序 source set。
入口点¶
阅读 src/mod_manager.h、src/mod_manager.cpp。refresh_mod_list、load_modfile、
load_mods_list、check_mods_list 与 worldfactory 的创建/读取是主要入口。
数据所有权¶
manager 拥有发现的 MOD_INFORMATION、dependency state 与 migration map；WORLD 拥有
active Mod ID 顺序；各 factory 拥有从这些 Mod path 加载的具体对象。
依赖¶
Mod 加载依赖 filesystem path、modinfo.json、dependency-tree 规则、worldfactory、JSON
dispatch、稳定 ID、obsoletion/migration data、localization 与可选 Lua manifest。
生命周期¶
启动时发现 core/user Mod 目录，验证 metadata/dependency；world 选择有序集合；协调缺失/ 重命名 Mod；随后按顺序加载数据和脚本；列表随 world 持久化。
不变量¶
Mod ID 唯一有效；不能依赖自身；dependency 位于 dependent 前；world order 无重复； 缺失 Mod 需明确 migration 或用户决定；source attribution 保留 Mod origin。
扩展点¶
metadata、dependency、conflict、obsoletion 与 migration 用数据表达。新 loader phase 必须 保持确定顺序、失败诊断、来源归属和 world 检查。
序列化¶
mods.json 保存 world 的有序 Mod ID，manager registry 重新发现。重命名/移除需提供
migration，不能静默重写或破坏已有 world。
测试¶
使用 tests/worldfactory_test.cpp、JSON loading、dependency error、duplicate ID、missing
Mod、migration、conflict 和完整 example-Mod load；含 Lua 时加入 manifest 验证。
性能¶
发现与 JSON load 是启动成本。避免重复遍历目录、不稳定排序，以及为一个 metadata 查询重载全部 registry。
CCB 差异¶
CCB bundled Mod、migration table、Lua v5 manifest 与接受的上游内容构成自己的兼容集。 不能替换成其他项目的默认 Mod list 或加载政策。
技术债务¶
发现、用户决定、依赖解析和数据加载通过启动流程耦合。未来拆分必须先保持准确顺序与 诊断，再讨论行为变化。