Подключаем ИИ-агентов

Речь про агента с доступом к файловой системе — он читает твой сейв и логи, пишет .ks прямо в папку игры и разбирает результат полёта. Это не «ИИ играет за тебя»: кнопки жмёшь ты, агент работает с текстом вокруг игры.

Зачем это здесь: KSP — игра, где почти всё состояние лежит обычным текстом на диске. Сейв, конфиги модов, логи, скрипты kOS — всё читается и правится без специальных инструментов. Поэтому агент оказывается неожиданно полезным именно тут.

Про рабочий цикл и сценарии — Нейросеть как второй пилот. Эта статья про техническую часть: как подключить и что дать.

Что агент реально видит

Всё это — простые текстовые файлы в каталоге игры:

Именно из этих файлов взяты все цифры в этой вики — дальности антенн, коридоры работы приборов, границы космоса. Агент может сделать ровно то же самое.

Где лежит игра

Файл контекста — самое важное

Любой современный агент подхватывает файл с описанием проекта: у одних он называется AGENTS.md, у других CLAUDE.md. Положи его в корень папки с игрой — и агент перестанет каждый раз спрашивать, где что лежит.

Готовый шаблон, скопируй и правь под себя:

# KSP 1.12.5 — сборка «Оператор» (kerbal.ru)

## Что это
Kerbal Space Program 1.12.5 со сборкой «Оператор»: стоковая система,
упор на спутники, сеть связи, станции и автоматику через kOS.
Игра на русском. Описание сборки: https://kerbal.ru/Operator
Вики со всеми механиками: https://kerbal.ru/Operator/wiki/

## Где что лежит
- Скрипты kOS: `Ships/Script/*.ks` — это том `0:` внутри игры
- Сейв: `saves/Sky Net/persistent.sfs` (заменить на своё имя игры)
- Чертежи: `saves/Sky Net/Ships/VAB/*.craft`
- Лог сессии: `KSP.log`
- Логи ModuleManager: `Logs/ModuleManager/`
- Конфиги модов: `GameData/<мод>/`

## Карта: где искать ответ

Агент тратит большую часть времени не на решение, а на поиск — где вообще посмотреть.
Эта таблица снимает вопрос.

| Вопрос агента | Где ответ |
|---|---|
| Какие функции есть в библиотеке и что они возвращают | <a class="wikilink" href="kos-api.html" title="Каждая функция из lib/*.ks — что принимает, что возвращает, что делает с кораблём. Плюс порядок загрузки, соглашения об именах и настройки, которые задаются перед вызовом.">kOS: справочник библиотеки kerbal.ru</a> |
| Что происходит от `m_orbit(s)` до орбиты, где точки отказа | <a class="wikilink" href="kos-avtomatizaciya.html" title="Что происходит от строки m_orbit(s) до готовой орбиты: фазы подъёма, выбор схемы выведения, точки отказа и как читать телеметрию. Карта потока управления для отладки и для ИИ-агента.">Автоматизация запуска по шагам</a> |
| Как спросить у корабля высоту, орбиту, детали, науку | <a class="wikilink" href="kos-spravochnik.html" title="Что можно спросить у корабля из скрипта — высота, скорость, орбита, детали, ресурсы, наука, время. Сгруппировано по задачам, с рабочими примерами и граблями, на которые мы наступали.">kOS: справочник по данным корабля</a> |
| Почему модули устроены именно так | <a class="wikilink" href="kos-biblioteka.html" title="Как разложить скрипты по файлам-блокам вместо одной простыни: подъём, узлы, наука, телеметрия отдельно, а файл миссии только собирает их и задаёт цифры цели. С готовой структурой и разбором подводных камней.">kOS: библиотека модулей</a> |
| Что нельзя называть переменной, куда девается производительность | <a class="wikilink" href="kos-otladka.html" title="Почему скрипт «висит», ест кадры и не слушается руля: лимит инструкций, WAIT в циклах, блокировки управления, ошибки парсера и рабочий процесс с внешним редактором.">kOS: отладка и лимиты</a> |
| Разбор ошибок реальных первых запусков | <a class="wikilink" href="kos-vyvod-orbita.html" title="Инженерный журнал четырёх попыток вывести спутник скриптом kOS: почему ракета кувыркалась, куда делись 1500 м/с, отчего сломались антенны и как чинится каждая из этих бед.">Скрипт вывода на орбиту: разбор ошибок</a> |
| Как подключиться к терминалу снаружи игры | <a class="wikilink" href="kos-telnet.html" title="Как открыть терминал kOS наружу, почему обычный telnet-клиент не работает, готовый клиент на Python и что это даёт связке «человек + ИИ-агент».">kOS по telnet: пульт снаружи игры</a> |
| Не идёт связь, наука, управление | <a class="wikilink" href="diagnostika-svyazi.html" title="Почему пропало управление и не уходит наука: уровни управления, расчёт горизонта, где смотреть в сейве и логе, чек-лист от дешёвых проверок к дорогим.">Диагностика связи</a>, <a class="wikilink" href="chastoty.html" title="Как CommNet Constellation превращает связь в радиосеть с каналами: частота на каждой антенне, частоты у наземных станций, апгрейд станций за деньги и главная ловушка — станция без частоты.">Частоты и наземные станции</a> |
| Что вообще делает конкретный мод сборки | <a class="wikilink" href="mody-yadro.html" title="Полный разбор ядра «Оператора» — 21 мод: что делает каждый, зачем он здесь и какие служебные библиотеки тянутся следом.">Каталог модов: ядро сборки</a>, <a class="wikilink" href="mody-rasshirenie.html" title="36 рекомендованных и 3 опциональных мода «Оператора» — что даёт каждый, на каком этапе игры пригодится и где он на любителя.">Каталог модов: расширения</a> |

Исходники, если нужен код целиком, а не описание:
`Ships/Script/lib/*.ks` рядом с игрой либо
[kos/ в репозитории](https://github.com/plagness/kerbal.ru/tree/main/kos).

## Первые пять минут агента

Порядок, который экономит больше всего времени:

1. Прочитать `AGENTS.md` в корне папки игры — он положен установщиком и описывает **эту**
   установку: какая сборка, где вики, какие правила.
2. Открыть `.kerbalru-build.json` — состав сборки и дата установки. Отсюда видно, что за моды
   стоят, и не надо гадать.
3. Посмотреть `Ships/Script/missions/_template.ks` — образец файла миссии.
4. Если задача про полёт — прочитать <a class="wikilink" href="kos-avtomatizaciya.html" title="Что происходит от строки m_orbit(s) до готовой орбиты: фазы подъёма, выбор схемы выведения, точки отказа и как читать телеметрию. Карта потока управления для отладки и для ИИ-агента.">Автоматизация запуска по шагам</a> прежде, чем писать свой цикл
   подъёма: он уже написан и проверен.
5. Если что-то не работает — сначала `KSP.log` и `mission.csv`, потом гипотезы.

Чего делать не надо: писать собственный автопилот с нуля, когда нужен один вызов из библиотеки;
предлагать «как в ванильной KSP», не проверив конфиги сборки; трогать `saves/`.

## Правила
- Игру запускаю я. Никогда не пытайся её стартовать.
- НЕ ПИШИ в `saves/` и `GameData/` без моего явного разрешения.
  Читать оттуда — сколько угодно.
- Писать можно только в `Ships/Script/`.
- Числа бери из конфигов в `GameData/`, а не из общих знаний про KSP:
  сборка меняет баланс, и «как в ваниле» тут часто неверно.
- Каждый скрипт полёта — с логгером телеметрии в CSV.
- В скриптах обязателен порог аварийного прерывания.
- Язык kOS не переводим: код английский, комментарии русские.

## Мой стиль полёта
(допиши: круговые орбиты, наклонение 0°, без MechJeb, топливо впритык…)

Строчка про «числа бери из конфигов» экономит больше всего споров. Без неё агент уверенно расскажет про ванильную KSP, а у тебя стоит 60 модов, которые её переписали.

Настройка по инструментам

Общий принцип у всех одинаковый: запускай агента из папки игры — тогда он видит файлы и подхватывает файл контекста. Конкретные команды и названия флагов у инструментов меняются от версии к версии, так что сверяйся с их документацией; ниже — что важно именно для KSP.

Claude Code

Терминальный агент от Anthropic. Читает CLAUDE.md из текущего каталога.

cd "<путь к KSP>"
claude

Что настроить под игру: - Права. По умолчанию спрашивает подтверждение на запись. Разреши запись в Ships/Script/, а saves/ и GameData/ оставь на подтверждении — так он не тронет сейв случайно. - Длинные логи. KSP.log бывает на десятки мегабайт. Не проси «прочитай лог целиком» — проси искать по шаблону: «найди в KSP.log строки с [ERR за последний запуск».

Codex CLI

Терминальный агент от OpenAI. Читает AGENTS.md.

cd "<путь к KSP>"
codex

Особенности: - Работает в песочнице с ограничением записи — для нашей задачи это плюс: по умолчанию он не испортит сейв. - Уровень доступа выбирается при запуске; для работы со скриптами нужна запись хотя бы в рабочий каталог.

OpenCode

Открытый терминальный агент, умеет ходить в разные модели — облачные и локальные. Тоже читает AGENTS.md.

Ценен тем, что можно посадить на локальную модель: разбор CSV с телеметрией или поиск ошибок в логе не требует топовой модели, а гонять такое локально дешевле и приватнее. Для написания скриптов с нуля лучше модель посильнее.

Grok и обычный чат в браузере

Grok, как и любой чат без доступа к файлам, работает по схеме «копипаст»:

1. Ты открываешь .craft или CSV телеметрии и вставляешь кусок в чат.
2. Получаешь скрипт текстом.
3. Сохраняешь его сам в Ships/Script/.

Медленнее, но работает везде и без настройки. Для разового «напиши скрипт взлёта» этого достаточно. Не годится там, где нужно перебрать десяток файлов — например «найди, какие детали в сборке дают эксперимент X».

Что выбрать

Безопасность

Агент ошибается молча и быстро. Три правила, и проблем не будет.

1. Бэкап сейвов. Прежде чем первый раз пускать агента в папку игры:

cp -r "saves/Sky Net" "saves/Sky Net.backup"

На Windows — просто скопируй папку рядом.

2. Запись только в Ships/Script/. saves/ и GameData/ — на чтение. Испорченный сейв не чинится, а испорченный .ks стоит одного прогона. Это правило есть в шаблоне выше, но продублируй его в настройках прав самого агента — текстовая инструкция не гарантия.

3. Читай скрипт перед запуском. Не из недоверия, а чтобы понимать, что должно произойти: иначе не заметишь момент, когда пошло не так. Скрипт, который ты не можешь прочитать, — это лотерея, а не автоматизация (Когда автоматизировать, а когда лететь руками).

Отдельно: игру запускает человек. Агент не должен стартовать KSP — она открывается на минуты, ест всю память и рвёт ему обратную связь. Впиши это в файл контекста прямым текстом.

Рабочие запросы

Не «напиши скрипт для запуска», а конкретно. Шесть проверенных формулировок:

Разобрать аппарат.

Посмотри saves/Sky Net/Ships/VAB/спутник.craft. Перечисли научные приборы, для каждого найди в GameData рабочий диапазон высот и коэффициент передачи. Что из этого не работает на орбите 260 км?

Написать скрипт под аппарат.

Прочитай сейв, найди аппарат «LKO Relay A». Напиши Ships/Script/ascent.ks: круговая орбита 250 км, наклонение 0°, гравитационный разворот. Логгер телеметрии в CSV. Порог: глушить двигатель, если на подъёме вертикальная скорость ушла ниже нуля.

Разобрать неудачу.

Вот Ships/Script/ascent.csv с прошлого прогона. Апоцентр перелетел на 40 км. На какой секунде профиль разошёлся с планом и что поправить в скрипте?

Найти ошибки модов.

Найди в KSP.log строки [ERR и [EXC за последний запуск, сгруппируй по моду и скажи, какие из них наши, а какие — известный шум чужих модов.

Поиск по конфигам.

Найди в GameData все детали с ModuleScienceExperiment, доступные на открытых мной технологиях, размером 0,625 м и меньше. Отсортируй по науке, которую можно передать по радио.

Проверить сеть связи.

Посчитай по сейву, на каком проценте витка у аппарата есть прямая видимость ЦУПа. Формулы возьми из https://kerbal.ru/Operator/wiki/diagnostika-svyazi.html

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

Чего ждать и чего не ждать

Хорошо получается: скучный код (циклы, проверки, математика, логирование), поиск по десяткам конфигов, разбор длинных логов и CSV, рефакторинг накопившихся скриптов, расчёты Δv и фазовых углов.

Плохо получается: угадать физику конкретной ракеты — асимметричную тягу, странную аэродинамику, поведение на грани TWR. Нормальный результат — это две-три итерации: первый прогон вскрывает расхождение, второй его чинит, третий уходит в библиотеку.

Меняется с telnet: если включить telnet-сервер kOS (kOS по telnet: пульт снаружи игры), агент получает живой терминал корабля — сам запускает скрипт, сам читает ошибки с номерами строк, сам снимает телеметрию. Цикл «правка → прогон → разбор» сокращается с минут до секунд. Виджеты через telnet недоступны, только текст.

Не получается вообще: летать в реальном времени. Между «скрипт запущен» и «файл прочитан» агента в контуре нет. Нужна реакция сейчас — это MechJeb или твои руки.

Практический вывод: агент не заменяет понимание механики, он снимает рутину вокруг него. Поэтому начинать стоит не с «напиши мне полёт», а с «разбери, почему не сработало» — там польза видна сразу и цена ошибки нулевая.