MVM - 模组版本管理器

[left]
[img width=400]https://i.ibb.co/PXqwtW9/INTRODUCTION-Test-kleiner.png[/img]
[/left]

[b]Mod Version Manager (MVM)[/b] 是一个面向 Mod Organizer 2 的、可感知分支轨道的 Nexus 版本检查器与受保护的元数据修正插件。它的诞生源于一个在大型模组列表中越来越常见的问题：MO2 可能会报告一个更新，但那个"更新"的 Nexus 文件实际上属于一个完全不同的变体、分辨率、安装方式、版本、翻译、可选包或发布轨道。

MVM 的决定性区别在于，它[b]不会[/b]简单地将你已安装的模组与 Nexus 模组页面上显示的全局最新版本进行比较。相反，它以[b]你所安装文件的精确 Nexus File ID[/b] 为起点，确定匹配的文件/变体轨道，然后检查[b]在同一轨道内[/b]是否存在真正更新的文件。

这一区别在那些包含诸如 2K / 4K / 8K、Full / Lite、REDmod / Non-REDmod、Legacy / Next-Gen、SE / AE / VR、语言包、可选文件、技术辅助文件或作者专属发布分支等组合的 Nexus 页面上至关重要。来自其他分支的较新上传会被视为[b]替代版本[/b]，而不会自动被视为你已安装文件的更新。

MVM 还刻意区分了三个常常被混淆的值：MO2 为已安装模组存储的版本、附加在精确 Nexus 文件上的版本，以及 MO2 存储的[b]最新版本 (Newest Version)[/b] 值。这使 MVM 能够识别 MO2 的误报警告，而不会盲目覆盖已安装版本或将无关的 Nexus 元数据强行写入你的设置中。

如果你只是想要一个手动强制版本号的工具，MVM 是有意做得更为保守的。它的宗旨是[b]先做出文件级别、轨道感知的判断[/b]，只有在结果通过其安全性和置信度检查时，才提供自动修正。


[left]
[img width=400]https://i.ibb.co/JFmJB7h4/REQUIREMENTS-Test.png[/img]
[/left]

Mod Version Manager 直接安装到 Mod Organizer 2 中。它不需要作为常规游戏模组安装，也不会将文件放入你的游戏目录。

[b][color=#1155cc]前置要求[/color][/b]

• 支持 Python 插件的 Mod Organizer 2
• 用于 Nexus 文件列表检查的互联网连接
• 用于在线分析的个人 Nexus Mods API 密钥

[b][color=#1155cc]已测试环境[/color][/b]

• Mod Organizer 2 v2.5.2
• 所测试 MO2 环境使用的 Python 3.12 / PyQt6 运行时
• 主要实机测试环境：Cyberpunk 2077

[b][color=#1155cc]可选兼容性[/color][/b]

• MVM 本身不需要任何外部框架
• 当 Nexus 元数据足够清晰时，通用变体匹配也可在内置的游戏专属词汇表之外正常工作

Nexus API 密钥[b]仅在当前会话中保存在内存里[/b]。MVM 不会将密钥保存到其设置、日志、扫描报告或诊断包中。

MVM 为 Cyberpunk 2077、Skyrim Special Edition / Skyrim VR、Fallout 4 和 The Witcher 3 包含了额外的变体词汇，同时保持核心匹配器的通用性。内置游戏规则提高了对常见区分的识别能力，例如 REDmod / Non-REDmod、SE / AE / VR 和 Legacy / Next-Gen。


[left]
[img width=400]https://i.ibb.co/yCBYJhf/FEATURES-Test.png[/img]
[/left]

MVM 围绕一个原则设计：[b]在将某个 Nexus 文件称为更新之前，先确定它是否真的与你所安装的文件相关[/b]。

该插件结合了精确 File-ID 匹配、变体分类、受保护的元数据修正、全列表分析和恢复工具，而不是将模组页面上的最新文件视为普遍适用。

• [b]精确的 Nexus File-ID 锚定[/b] — MVM 读取与已安装下载相关联的 Nexus File ID，并以该精确文件作为分析的起点。

• [b]轨道感知的更新检测[/b] — 较新的文件会在已安装文件所在轨道内进行评估。不同分辨率、版本、安装类型、翻译、可选分支和其他变体可以保持可见，而不会被误分类为更新。

• [b]真实更新 vs 替代版本[/b] — MVM 区分真正的同轨更新与那些全局上可能更新但并不替换已安装变体的替代文件。

• [b]更安全的时间线判断[/b] — 在可用的情况下，利用 Nexus 文件更新谱系来追踪后继关系。上传时间和版本比较被用作额外的回退信号，而不是仅依赖一个全局版本字段。

• [b]灵活的版本解析[/b] — 支持常规版本号以及许多字母数字和作者特有的方案，例如 2.1.1B、2.1.1C2、beta / rc / hotfix 变体、f1.02、1.0.5-rp 及类似格式。

• [b]受保护的 MO2 元数据修正[/b] — 当 MVM 确认 MO2 存储的[i]最新版本[/i]值有误时，它可以修正该元数据而不替换已安装的模组文件。已安装版本不匹配的情况保持只读，不会被静默改写。

• [b]全扫描、选中模组扫描和安全批处理工作流[/b] — 扫描完整的 MO2 列表或仅扫描选中的模组，搜索结果，查看置信度，并仅对通过现有自动修正资格门槛的行应用批量修正。

• [b]聚焦式全扫描过滤器[/b] — v1.0.0 包含用于更新、不匹配、不明确情况和错误的[i]仅需操作[/i]过滤器，以及用于实际符合受保护自动修正条件的条目的[i]仅安全修正[/i]过滤器。

• [b]自动分类不足时的手动控制[/b] — 提供手动轨道规则、忽略模组规则和忽略更新版本，用于处理边缘情况，同时不削弱全局安全规则。

• [b]回滚、诊断与弹性 API 处理[/b] — 内置持久化修正备份、事务日志、经验证的批量回滚、会话缓存、请求去重、重试/退避、隔离的 API 错误、API 密钥验证、JSON/CSV 扫描导出、可复制的结果详情和脱敏诊断包。

MVM 从不安装、更新、替换或删除你模组的实际文件。其自动修正路径有意保持狭窄：只有在精确已安装文件、轨道判断和置信度门槛均被认为安全后，才修正 MO2 存储的[b]最新版本[/b]元数据。


[left]
[img width=400]https://i.ibb.co/Vpgnk6DQ/INSTALLATION-Test.png[/img]
[/left]

MVM 是一个 Mod Organizer 2 插件。请将其直接安装到 MO2 插件目录中，而不是通过常规模组列表安装。

[b][color=#1155cc]安装[/color][/b]

1. 下载最新的 Mod Version Manager 压缩包。

2. 完全关闭 Mod Organizer 2。

3. 解压压缩包，将其中包含的 [b]mod_version_manager[/b] 文件夹复制到：

[code]
<Mod Organizer 2>\plugins\[/code]
4. 生成的结构应如下所示：

[code]
<Mod Organizer 2>\plugins\mod_version_manager\
init.py
mod_version_manager.py
game_rules.py
i18n.py
data\
logs\[/code]
5. 启动 Mod Organizer 2。

6. 从 MO2 插件界面打开 MVM，或使用模组列表 / 版本列右键菜单中可用的 MVM 选项。

如果插件正确加载，MVM 的诊断窗口、扫描工具和右键菜单操作将在 MO2 中可用。


[b][color=#1155cc]更新[/color][/b]

对于常规更新，保留现有的运行时数据，仅用较新的包替换插件代码。

1. 完全关闭 MO2。

2. 如果你想保留设置、规则、备份和历史记录，请保留以下文件夹：

[code]
<MO2>\plugins\mod_version_manager\data\
<MO2>\plugins\mod_version_manager\logs\[/code]
3. 将新的 [b]mod_version_manager[/b] 文件夹覆盖到现有文件夹上并替换 Python 文件，然后再次启动 MO2。

如需完全干净地重新安装，请至少先备份 [b]data[/b] 文件夹。从更早的候选发布版本布局升级的用户，应允许 MVM 执行其旧存储迁移，然后再手动删除旧的运行时文件夹。


[b][color=#1155cc]卸载[/color][/b]

1. 完全关闭 Mod Organizer 2。

2. 删除以下文件夹：

[code]
<MO2>\plugins\mod_version_manager\[/code]
3. 再次启动 MO2。

MVM 不修改你的游戏安装，也不需要在各个 MO2 配置文件中移除。删除插件文件夹也会移除本地存储的 MVM 设置、规则、回滚数据和日志，除非你事先进行了备份。


[left]
[img width=400]https://i.ibb.co/s914tpHD/HOW-TO-USE-Test.png[/img]
[/left]

MVM 可用于单个可疑模组、一组选中的模组，或完整的 MO2 模组列表。

最安全的工作流程是让 MVM 先识别精确的已安装文件，查看生成的状态，仅在 MVM 明确将条目标记为符合条件时才使用修正功能。


[b][color=#1155cc]检查单个模组[/color][/b]

1. 在 MO2 中选择或右键点击你想要检查的模组。

2. 打开 MVM 诊断视图并运行本地分析。

3. 如需要，输入当前会话的 Nexus API 密钥，然后获取 Nexus 文件信息。

4. 在采取任何操作之前，查看检测到的 File ID、已安装轨道、Nexus 文件版本、MO2 值、状态和置信度。

可能的结果包括：已是最新、真实更新、更新的同版本文件、替代变体、错误的 MO2 最新版本元数据、已安装版本不匹配、分类不明确或 API/访问错误。

[b]重要：[/b]已安装版本不匹配是有意设为只读的。MVM 不会为了让这些值看起来一致而改写已安装版本。


[b][color=#1155cc]使用全扫描[/color][/b]

1. 打开[b]全扫描[/b]并扫描完整的模组列表，或者当你只想检查较小的一组时，使用选中模组工作流。

2. 使用搜索字段和状态过滤器缩小结果列表。[b]仅需操作[/b]会隐藏那些仅为最新或仅含替代版本的条目。

3. 当你特别想查看通过 MVM 自动修正工作流所使用的相同安全性和置信度门槛的条目时，使用[b]仅安全修正[/b]。

结果表格还可以显示语义状态颜色和置信度信息。扫描报告可以导出为 JSON 或 CSV，单个行的详细信息可以从右键菜单中复制。


[b][color=#1155cc]修正、规则与恢复[/color][/b]

1. 仅在 MVM 将该情况识别为安全的 MO2 元数据修正时才应用修正。批量修正使用相同的资格规则，不会扩大 MVM 允许写入的范围。

2. 对于不寻常的 Nexus 页面，使用手动轨道规则或忽略规则，而不是强迫匹配器接受不确定的结果。

3. 如果需要进行故障排除，请使用 API 密钥测试、日志、自检和诊断包工具。MVM 保留修正备份和事务信息，以便可验证或回滚受支持的更改。

MVM 的安全模型是刻意保守的。真实更新、替代变体、不明确的匹配、API 错误和已安装版本不匹配均被排除在自动元数据修正之外。


[left]
[img width=400]https://i.ibb.co/M5KZnsPR/COMPATIBILITY-Test.png[/img]
[/left]

• Mod Organizer 2 v2.5.2 — 主要测试的 MO2 版本
• Cyberpunk 2077 — MVM 开发期间的主要实机测试环境
• 内置变体词汇表：Cyberpunk 2077、Skyrim Special Edition、Skyrim VR、Fallout 4 和 The Witcher 3
• 当有足够的 File-ID 和 Nexus 元数据可用时，通用 Nexus 支持的 MO2 模组仍可在这些游戏专属规则之外进行分析

MVM 不绑定于某一个游戏的模组文件，因为它主要基于 MO2 元数据和 Nexus 文件信息工作。然而，游戏页面和作者的命名惯例可能差异很大，因此不明确的情况会被有意报告为不明确，而不是猜测。

不声称每个 Nexus 页面都能被自动分类。该插件的设计目标是在可用元数据不足时安全地失败。


[left]
[img width=400]https://i.ibb.co/zTfmj2nr/LOCALIZATION-Test.png[/img]
[/left]

MVM 内置以下用户界面本地化：

• 英语
• 德语
• 法语
• 波兰语
• 俄语
• 西班牙语
• 意大利语
• 葡萄牙语（巴西）
• 简体中文

本地化的六步快速导览已包含在稳定版本中，并在所有捆绑的 UI 语言中可用。


[left]
[img width=400]https://i.ibb.co/whzzxVQS/KNOWN-ISSUES-NOTES-Test.png[/img]
[/left]

MVM 的设计倾向于显示明确的未解决状态，而不是看似自信但不安全的自动修正。

[b][color=#1155cc]已知问题[/color][/b]

• 不可用、隐藏、已删除或访问受限的 Nexus 模组或文件端点可能返回 HTTP 403 等 API 错误。MVM 会报告受影响的条目并将失败隔离，而不是将缺失数据视为有效的更新判断。

• 当 Nexus 元数据未提供足够证据以识别可靠轨道时，极其异常或不一致的文件命名仍可能产生不明确的结果。这些情况会被有意阻止自动修正。


[b][color=#1155cc]备注[/color][/b]

• Nexus API 密钥仅存在于会话中，不会被有意持久化或写入诊断导出。

• 安全修正仅更改 MO2 存储的[b]最新版本[/b]元数据。MVM 不会替换已安装的压缩包、下载新的模组版本或修改模组的游戏文件。

• [b]仅安全修正[/b]是一个视图过滤器，而不是更弱的安全模式。它使用与常规受保护批量工作流相同的自动修正资格门槛。


[left]
[img width=400]https://i.ibb.co/7qDsMKd/SUPPORT-Test.png[/img]
[/left]

如果你遇到错误分类、意外警告、API 问题、UI 问题或其他错误，请提供足够的信息以重现该问题。MVM 包含专为支持而设的专用日志记录和诊断工具。

报告问题时，请包含：

• 你的 Mod Version Manager 版本，例如 [b]v1.0.0[/b]
• 你的 Mod Organizer 2 版本以及该 MO2 实例管理的游戏
• 受影响的模组名称和 Nexus Mod ID（如果知道）
• 已安装的 Nexus File ID、显示的 MVM 状态以及相关结果的截图（如有可能）
• 生成的 [b]MVM 诊断[/b]包或相关日志部分（用于技术问题）

[b]不要[/b]发布你的 Nexus API 密钥。MVM 的诊断包设计为脱敏处理，但 API 密钥仍然绝不应手动包含在错误报告中。

详细的重现步骤对于变体分类问题尤其有用：提及你安装的确切 Nexus 文件以及 MVM 认为是更新或替代的文件。

欢迎反馈、边缘情况和异常 Nexus 文件结构的示例，因为它们有助于在不削弱其保守安全行为的前提下改进匹配器。


[left]
[img width=400]https://i.ibb.co/YFV3RyBm/CREDITS-Test.png[/img]
[/left]

特别感谢 [url=https://www.nexusmods.com/profile/ModOrganizerTeam]ModOrganizerTeam[/url] 创建并维护 Mod Organizer 2 — MVM 所构建的平台和插件环境。

感谢 Nexus Mods 提供 MVM 在线版本分析所使用的文件元数据和 API。

并感谢所有测试 MVM、报告边缘情况、提供日志并帮助针对真实 Nexus 页面验证轨道感知匹配器的人们。

特别感谢 MVM 之前的 MO2 版本修复工具背后的模组作者们。他们帮助证明了 MO2 的版本处理确实需要一些额外的帮助 — MVM 只是通过精确 File-ID 追踪、变体感知和更保守的安全模型将这个想法进一步推进。