neuromancer/rats-reРеконструирует устаревшие Windows-бинарные файлы в исходный код C, объединяя экспорт декомпилятора Ghidra с локальными LLM, создавая кандидатов, прошедших проверку компиляцией, и отчёты на основе схожести.
# Rats! восстановление исходного кода с помощью локальных LLM Этот репозиторий — незавершённая реконструкция исходного кода `RATS.EXE`, оригинальной Windows-версии игры [*Rats!*](https://www.windowsgames.co.uk/rats.html) (1994) Шона О'Коннора. Проект собирает Win32-исполняемый файл с помощью Microsoft Visual C++ 4.1 под [wibo](https://github.com/neuromancer/wibo) и может быть протестирован в [DREAMM](https://dreamm.aarongiles.com/). Эксперимент исследует, насколько далеко локальные LLM могут продвинуть реконструкцию исходного кода на небольшой, но реалистичной кодовой базе, а не на игрушечном примере. Точность совпадения остаётся неравномерной, что здесь полезно: цель — показать реалистичную картину процесса и его текущих ограничений, а не прятать сложные функции. Реконструкция функций ограничена локальными LLM. Codex и Claude используются для настройки репозитория и оркестрации бенчмарков, но им не разрешено писать или редактировать реконструируемый исходный код. Если не указано иное, во всех экспериментах использовалась Qwen3.8 27B BF16 на MacBook Pro 2024 года с Apple M4 Max (16-ядерный CPU, 40-ядерный GPU) и 128 ГБ памяти. Подход работает — неидеально, но с пользой: на реконструкцию 36 сохранённых функций ушло в среднем 2m 32.1s на каждую (время по журналу). ## Установка Клонируйте с подмодулями или инициализируйте их после клонирования: ```sh git submodule update --init --recursive ``` Оригинальный исполняемый файл не включён. Скачайте бесплатную Windows-версию с [официальной страницы *Rats!*](https://www.windowsgames.co.uk/rats.html) и поместите её `RATS.EXE` в корень репозитория, чтобы использовать цели original-executable и binary-comparison. ## Часто используемые команды ```sh 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](https://github.com/decompme/compilers/releases/download/compilers/msvc4.1.tar.gz) с фиксированной контрольной суммой, необходимые библиотеки MSVC 4.1, совместимая с wibo `msvcrt40.dll` и DREAMM `4.0x21` загружаются по требованию. Они остаются игнорируемыми локальными зависимостями сборки и не фиксируются в репозитории. ## Рабочий процесс реконструкции Включённый в репозиторий каталог `ghidra/` содержит экспорт ассемблера и декомпилятора для всех 177 внутренних функций. Ассемблер является эталоном для сравнения; декомпилированный C — лишь семантическая затравка. Установите [`binary-recons`](https://github.com/gg-sl-oss/binary-recons) один раз, затем запускайте его из корня репозитория: ```sh 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](https://github.com/neuromancer/rats-re/blob/main/docs/MODEL_RESULTS.md). <details> <summary>Результаты моделей: 36 сохранённых функций и 3 отложенных адреса</summary> Большинство сохранённых кандидатов было сгенерировано с помощью [Qwen3.8 27B GGUF](https://unsloth.ai/docs/models/qwen3.8) от 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 | Попытки реконструкции для следующих адресов были исчерпаны без сохранения реализации исходного кода. Затраченное время указано суммарно по всем записанным попыткам. | Отложенный адрес | Затрачено времени | Результат | | --- | ---: | --- | | `0x00401000` | 10m 29.7s | Функция слишком велика для ограниченного первого прохода; сохранён исходный каркас 1.13% | | `0x00403840` | 13m 10.0s | Нет компилируемого кандидата; слишком велика для быстрого ограниченного прохода | | `0x00406674` | — | Пропущена: слишком велика для быстрого ограниченного прохода | </details> ## Благодарности Особая благодарность: - [Шону О'Коннору](https://www.windowsgames.co.uk/) за создание игры [*Rats!*](https://www.mobygames.com/game/52495/rats/) и за то, что оригинальная Windows-версия по-прежнему доступна на [официальной странице игры](https://www.windowsgames.co.uk/rats.html).
