basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN
    МануалИИИИ-агенты

    Сервер вместе с ИИ-агентом: роли, проверки, секреты

    Агент читает конфиги из git на компьютере и готовит команды, человек выполняет их на сервере и возвращает вывод. Root на сервере и секреты агенту не нужны: опись — путями, проверки — с маскировкой значений.

    Кто что делает

    Кто Что делает Чего не делает
    человек выполняет команды на сервере, присылает вывод, принимает решения («удаляем?», «какая почта?»), знает факты о железе и людях не правит файлы на сервере руками
    агент читает конфиги в git, находит проблемы, предлагает решение с рекомендацией, пишет команды с объяснением и откатом, коммитит правки не ходит на сервер; не видит и не повторяет секретов
    git общий источник правды: что на сервере, то и в репозитории не хранит секретов и данных

    Работа идёт по кругу:

    1. опись (только пути)  →  2. агент: правка в репозитории + команды  →  3. человек: пробный прогон, вывод агенту
            ↑                                                                              ↓
    6. README/план обновлены  ←  5. проверка действием  ←  4. применение: git pull, up -d — по шагам, с «воротами»

    Десять правил процесса

    1. Опись — только пути и имена: find, docker compose ls, имена переменных. Содержимое .env агенту не нужно.
    2. Проверки — с маскировкой. Агенту нужен ответ «в этой строке настоящее значение или ${…}», а не само значение. Скрипт проверки печатает вид и длину («Конфиги серверов в git», шаг 5).
    3. Секреты генерируются и переносятся мимо экрана (openssl rand, install -m 400, printf '%s'). Агент пишет такие команды, а в выводе — «сменён», «не 0», но не значение.
    4. У каждой команды — объяснение: что она делает, что меняет, что ожидается в выводе.
    5. «Ворота»: «ожидается OK; если нет — стоп, пришлите вывод». Человеку не приходится гадать, можно ли идти дальше («Длинная инструкция — с проверками «ожидается X, иначе стоп»»).
    6. Откат — заранее. Копия старого файла до правки и команда возврата — в том же сообщении.
    7. Зависимые шаги — одной командой: секрет до git pull, git pull до rm («Зависимые шаги — одной строкой через &&»).
    8. Одна тема — один коммит, в сообщении — что и зачем. История читается как журнал работ.
    9. Решения записываются: README сервера («Сделано», «Открыто», «Оставлено сознательно»), отдельные планы на большие задачи. Следующая сессия агента начинает с них, а не с нуля.
    10. Большое — отдельной задачей. У бэкапов и паролей свой план с вопросами, их не делают «заодно» посреди наведения порядка.

    Сколько доступа давать агенту

    Схема Что даёт Цена
    агент без доступа к серверу (описано здесь) агент не может ничего сломать и не видит лишнего; всё идёт через git медленнее: каждый шаг — через человека
    агент с SSH на сервер быстро агент работает на живом сервере с правами root; любой промах — сразу на проде; секреты в поле зрения
    Remote-SSH в редакторе (агент «внутри» сервера) всё видно прямо на сервере то же, что SSH: агент исполняет команды на сервере
    агент пушит в репозиторий, CI выкатывает без ручных шагов нужна инфраструктура; ошибка выкатывается сама

    Первая схема медленнее: каждую команду запускает человек. Зато агент ничего не сломает на сервере и не увидит ни одного секрета. Когда на серверах живые сайты и пароли, это перевешивает.

    Если не работает

    Промахи агента и как их ловить

    Агент принял комментарий в конфиге за факт

    Причина
    В файле «настроено под HDD», а сервер давно на SSD — стек переехал. Агент построил на этом рекомендацию.
    Делаем
    Факты о железе, тарифе и людях агент спрашивает у человека.

    Агент сделал вывод по имени файла

    Причина
    «Скрипт update-x.sh обновляет файл X», а скрипт писал в другой путь, и X не обновлялся месяцами.
    Делаем
    Агент читает код, а не имя, а человек переспрашивает, проверено ли это.

    Агент «починил» то, что не было сломано

    Причина
    Поиск нашёл basicauth.users, агент решил, что в файле хэш, а там была ссылка ${…}. Скрипт «переноса» попытался перенести ссылку.
    Делаем
    Сначала смотрим на строку (замаскированно), потом чиним; скрипт правки — с автооткатом по хэшу конфига («Скрипт правки — с автооткатом»).

    Агент принял закрытый чат за отказ

    Причина
    Редактор перезапустился посреди работы, и вызовы вернулись как «отклонены».
    Делаем
    При сомнении агент спрашивает, а не решает за человека.

    Промахи человека и чем помогает агент

    Опечатка в команде дала ошибку с непонятным текстом

    Причина
    Например, лишний знак =: REPO==name вместо REPO=name перед git remote add даёт is not a valid repository name.
    Делаем
    Агент разбирает вывод и даёт исправление (git remote set-url), а не ту же команду ещё раз.

    Человек вставил в чат команду с паролем

    Причина
    Например, команду бэкапа с паролем в аргументе.
    Делаем
    Агент не повторяет значение, проверяет, не попало ли оно в git, и предлагает смену пароля без вывода на экран и способ обходиться без пароля в команде («Пароль — не в аргументах команды»).

    «Что из этого я уже сделал?»

    Причина
    Длинная серия шагов путает.
    Делаем
    Агент отвечает таблицей «шаг — сделан / не нужен / осталось» и даёт только оставшееся.

    Команда запущена не на том сервере

    Причина
    Неясно, что она там изменила.
    Делаем
    Агент оценивает последствия (часто — никаких: строки уже удалены) и даёт проверку, которая это подтверждает.

    Как проверить

    Признаки, что порядок наведён:

    cd /opt && git status --short                              # пусто — сервер совпадает с репозиторием
    find /srv/secrets -exec stat -c '%a %U %s %n' {} \;        # секреты на месте, права 400/700
    stat -c '%a %n' /opt/*/.env                                # 600

    И в репозиториях: README каждого сервера описывает его как есть, а в разделах «Открыто» — только то, что правда ждёт решения.