Rats! восстановление исходного кода с помощью локальных LLM

Этот репозиторий — незавершённая реконструкция исходного кода RATS.EXE, оригинальной Windows-версии игры Rats! (1994) Шона О'Коннора. Проект собирает Win32-исполняемый файл с помощью Microsoft Visual C++ 4.1 под wibo и может быть протестирован в DREAMM.

Эксперимент исследует, насколько далеко локальные LLM могут продвинуть реконструкцию исходного кода на небольшой, но реалистичной кодовой базе, а не на игрушечном примере. Точность совпадения остаётся неравномерной, что здесь полезно: цель — показать реалистичную картину процесса и его текущих ограничений, а не прятать сложные функции.

Реконструкция функций ограничена локальными LLM. Codex и Claude используются для настройки репозитория и оркестрации бенчмарков, но им не разрешено писать или редактировать реконструируемый исходный код.

Если не указано иное, во всех экспериментах использовалась Qwen3.8 27B BF16 на MacBook Pro 2024 года с Apple M4 Max (16-ядерный CPU, 40-ядерный GPU) и 128 ГБ памяти. Подход работает — неидеально, но с пользой: на реконструкцию 36 сохранённых функций ушло в среднем 2m 32.1s на каждую (время по журналу).

Установка

Клонируйте с подмодулями или инициализируйте их после клонирования:

git submodule update --init --recursive

Оригинальный исполняемый файл не включён. Скачайте бесплатную Windows-версию с официальной страницы Rats! и поместите её RATS.EXE в корень репозитория, чтобы использовать цели original-executable и binary-comparison.

Часто используемые команды

make                 # build out/RATS_RE.EXE, .map, .obj, and .asm
make toolchain       # download, extract, and verify Microsoft Visual C++ 4.1
make run             # launch the rebuilt executable in DREAMM
make run-original    # launch the preserved original RATS.EXE
make test            # bounded DREAMM smoke test of the rebuilt executable
make test-original   # bounded DREAMM smoke test of the original executable
make debug           # start the rebuilt executable in DREAMM's debugger
make report          # report similarity for every reconstructed function
make compare-func FUNC=SaveHighScores ADDR=00409092

Архив MSVC 4.1 с фиксированной контрольной суммой, необходимые библиотеки MSVC 4.1, совместимая с wibo msvcrt40.dll и DREAMM 4.0x21 загружаются по требованию. Они остаются игнорируемыми локальными зависимостями сборки и не фиксируются в репозитории.

Рабочий процесс реконструкции

Включённый в репозиторий каталог ghidra/ содержит экспорт ассемблера и декомпилятора для всех 177 внутренних функций. Ассемблер является эталоном для сравнения; декомпилированный C — лишь семантическая затравка.

Установите binary-recons один раз, затем запускайте его из корня репозитория:

python3 -m pip install -e /path/to/binary-recons
binary-recons --next-function           # reconstruct the next safe missing target
binary-recons --address 0x409092        # reconstruct or improve a specific target

Инструмент автоматически находит Qwen в стандартном кэше Hugging Face; BINARY_RECONS_MODEL_PATH может переопределить его. binary-recons.toml удерживает автоматический выбор в пределах диапазонов игрового кода, запускает и останавливает llama.cpp, а также определяет транзакционные файлы и команду binary-comp. Каждый ограниченный запуск засевает одну функцию из Ghidra, запрашивает у Qwen точечные исправления компиляции или расхождений в ассемблере и сохраняет лучшего безопасно компилирующегося кандидата. Используйте --target-score 95 для более глубокого прохода или --dry-run-prompt, чтобы просмотреть промпт без загрузки Qwen.

Результаты замеров запусков локальных моделей записаны в docs/MODEL_RESULTS.md.

Результаты моделей: 36 сохранённых функций и 3 отложенных адреса

Большинство сохранённых кандидатов было сгенерировано с помощью Qwen3.8 27B GGUF от Unsloth в BF16 (Qwen3.8-27B-BF16, обслуживалась как qwen3.8-27b-bf16) через llama.cpp с контекстом в 32 768 токенов и пресетом модели qwen. Текущий рабочий процесс использует декомпиляцию Ghidra как механическую затравку, запрашивает у Qwen только осмысленный контракт и ограниченные правки исходного кода, следует за валидными правками как траекторией восстановления и сохраняет лучший результат по замерам binary-comp. Gemma 4 31B IT BF16 также тестировалась в бенчмарке, но ни один из её кандидатов не сохранён в дереве исходников.

Показатели ниже были пересчитаны по текущему дереву исходников с помощью MSVC 4.1 и binary-comp 16 августа 2026 г. Записанное время включает запуск управляемого сервера, генерацию или восстановление, сборку и сравнение для сохранённого кандидата. Оно не включает неудачные исследовательские запуски и циклы правок, выполненные после того, как возобновляемый кандидат уже был получен; они остаются доступными в журналах запусков.

Адрес	Функция	Текущее сходство	Записанное время
0x0040215C	IsLevelIndexInRange	65.31%	3m 06.4s
0x00402205	ShowLevelComplete	93.96%	5m 26.1s
0x0040250C	SubmitHighScore	97.37%	1m 49.7s
0x004026D0	RenderScoreboard	95.40%	2m 30.9s
0x00402BF3	AddLevelToTable	73.85%	4m 04.6s
0x00402DC6	UpdateGameDisplay	78.18%	1m 36.4s
0x00402EE7	GetLevelDisplayInfo	71.70%	2m 15.9s
0x00402FD5	GetLevelIndex	87.27%	5m 48.3s
0x00403430	IsBombAtLevel	80.62%	27.3 s
0x00403607	PlaceLevel	80.00%	2m 32.6s
0x00404764	DrawLevelIndicator	97.33%	1m 35.6s
0x0040499F	RenderCornerGlyph	69.83%	1m 50.9s
0x00404D6E	DrawBitmapPair	98.67%	1m 04.6s
0x00404E3B	RenderBitmapToWindow	94.74%	26.4 s
0x00404ECE	DrawBitmapToWindow	95.59%	59.3 s
0x00404F8B	DrawScore	96.20%	1m 32.4s
0x0040507F	DrawScorePanel	97.97%	2m 45.0s
0x0040525D	DrawScoreDigits	94.20%	2m 13.7s
0x00405343	RenderScoreOverlay	77.78%	1m 28.1s
0x0040546B	DrawFrameBorder	84.93%	37.0 s
0x0040552E	ExplodeBomb	64.71%	1m 50.9s
0x0040560E	RenderExplosionWave	85.07%	5m 40.0s
0x0040591A	DrawBombExplosion	89.31%	1m 45.8s
0x00405AF5	DrawPausedOverlay	96.21%	1m 05.1s
0x00405C52	HighScoreDialogProc	79.82%	41.5 s
0x00405DB8	ScorePanelDialogProc	50.34%	1m 53.1s
0x00405F72	DemoVersionDialogProc	46.31%	4m 18.5s
0x004061D3	OrderDialogProc	53.16%	10m 46.5s
0x00408854	DrawStartButton	70.80%	1m 35.6s
0x00408A51	UpdateMainMenuState	97.56%	28.9 s
0x00408AD3	InitializeGameLevel	83.72%	5m 35.7s
0x00408E6A	LoadLevelData	77.50%	52.5 s
0x00408F02	LoadHighScores	79.61%	1m 15.0s
0x00409092	SaveHighScores	94.12%	1m 25.9s
0x0040910C	LoadLevelBitmaps	98.93%	7m 08.4s
0x00409DB6	IsRatsHelpFile	91.67%	41.5 s

Попытки реконструкции для следующих адресов были исчерпаны без сохранения реализации исходного кода. Затраченное время указано суммарно по всем записанным попыткам.