Skyrim ModOps

A Python and PowerShell toolkit for keeping a Skyrim Special Edition modlist in Mod Organizer 2 (MO2) up to date and working: predict which SKSE plugins the game will refuse, find and install updates with fail-closed FOMOD choices, repair the profile after an install, rerun generators, keep a Traditional Chinese translation current, and check the result in the running game. Every verdict comes from deterministic code; a model only translates text or answers bounded visual questions during runtime QA.

It was written for one modlist on one Windows PC and is published as it is. Read the code before you point it at an instance you care about, and keep backups: several commands move, replace or delete files inside MO2.

Quick start / 快速開始

1. Download SkyrimModOps.exe from the Releases page (or build it: powershell -File tools\Launcher\Build-Launcher.ps1). 從 Releases 下載 SkyrimModOps.exe（或自行建置）。
2. Run it. It carries the whole toolkit, finds a portable MO2 instance and the game on its own, and offers to download a pinned, SHA256-checked Python from python.org when none is installed. The language (繁體中文 / English) is under Settings. 執行後會自動找到可攜版 MO2 與遊戲；沒有 Python 時會提議從 python.org 下載固定版本並核對 SHA256。語言在「設定」切換。
3. Under Settings, pick your main profile and press "Create a QA profile from the main profile" (a copy without saves that uses its own save folder), then "Create formal-save baseline" if you want runtime QA. 在「設定」選擇正式設定檔，按「從正式設定檔建立測試用設定檔」；要做實機測試再按「建立正式存檔基準」。
4. To add a mod, open "Add a mod", paste its Nexus URL and follow the recommendation: install into the QA profile (verified, then synced) or into a separate trial profile. 要新增模組，到「安裝模組」貼上 Nexus 網址，依建議安裝到測試用設定檔或試用設定檔。
5. On Home, press "Start full automatic update". It updates the QA profile, verifies it, and only then copies the lists to the main profile. When Nexus files need a click on the website (accounts without Premium), the pages open and the update resumes by itself once the files are in your Downloads folder. 在「首頁」按「開始全自動更新」：先更新並驗證測試用設定檔，通過後才同步到正式設定檔；需要在 Nexus 網頁按下載時會自動開頁， 檔案下載完成後自動接續。

Requirements

• Windows 10/11, Windows PowerShell 5.1; Python 3.11 or newer (standard library only; the launcher can download it)
• A portable MO2 instance with Skyrim Special Edition and SKSE
• Optional: 7-Zip (MODOPS_7Z if it is not in Program Files\7-Zip), a Nexus Mods API key for update checks (NEXUS_API_KEY), an OpenAI-compatible local model server for translation, and the System-One Mapika/decider-2b-vision model for driving runtime QA

Setup

Copy config/local-settings.example.json to config/local-settings.json and fill in this machine's folders, or set the matching environment variables (they win over the file):

Key	Environment variable	Folder
mo2_root	MODOPS_MO2_ROOT	the MO2 instance (the folder with ModOrganizer.exe)
game_data	MODOPS_GAME_DATA	the game's Data folder
backup_dir	MODOPS_BACKUP_DIR	where backup-local mirrors local mods; outside MO2 and this folder
decider_dir	MODOPS_DECIDER_DIR	optional: the decider-2b-vision folder (with .venv and model)

A command that needs a folder nobody configured stops with SETTING_MISSING. Your own decisions (FOMOD answers, mods to keep disabled, config keys to preserve, generators, the performance baseline, the names of your QA and main profiles) live in config/modops-rules.json; edit qa_profile and formal_profile first.

Tools

Command	Use
python tools/modops.py auto	Everything in one command: hardware, display settings, Nexus and GitHub updates, then update-cycle; run it again to resume after a manual step
python tools/modops.py update-cycle / next / status	A whole update (install, reconcile, carry-over, config merge, overlays, zh-TW, generators, runtime QA, profile sync, cleanup) with gating, rollback and resume
python tools/modops.py skse-scan	Predict which SKSE plugin DLLs the loader refuses on the installed runtime
python tools/modops.py mod-check <Nexus URL or id>	Before installing a mod: its requirements, game-1.7 notes, your rules, a verdict and whether to try it in a separate profile first
python tools/modops.py nexus-check / github-check	Newer files on Nexus and newer GitHub releases of installed mods
python tools/modops.py install / install-list / fetch-github	Install archives with fail-closed FOMOD selection, an SKSE gate and rollback
python tools/modops.py plugins-check	Missing or late masters, plugins missing from plugins.txt
python tools/modops.py reconcile / carry-over / config-merge / overlay-sync	Repair a profile after an install
python tools/modops.py zhtw-check / zhtw-queue / zhtw-translate	Find untranslated strings, translate with a local model, import only validated rows
python tools/modops.py generate	Rerun Pandora or PGPatcher through MO2, verify the output, roll back on failure
python tools/modops.py qa-verdict / qa-roundtrip / crash-triage	Runtime verdict from logs and frame times, save round-trip check, the mod behind a crash
python tools/modops.py snapshot / restore / backup-local / restore-local	SHA256-verified snapshots and backups
tools/Launcher/Build-Launcher.ps1	Build SkyrimModOps.exe, the launcher described above
scripts/runtime/Invoke-QaLaunch.ps1	One observed game launch: dialogs, SKSE and crash logs, pilot scenarios, then qa-verdict
tools/nexus_mcp.py	A read-only Nexus Mods MCP server (stdio) for agents

python tools/modops.py --help and <command> --help list every option.

Tests

python -B -m unittest discover -s tests -p "test_modops*.py"
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/development/Test-Bounded-Native.ps1

The tests build synthetic MO2 instances and never touch a real one.

Mod sources

The source policy keeps a mod's eligibility separate from provenance, permission, compatibility and safety checks. This toolkit ships no mod files and no third-party translations; respect each mod author's permissions.

License

MIT, see LICENSE. Skyrim, MO2, SKSE and the mods mentioned belong to their respective owners.