MODULE_05 · УРОК 5.3

Дизайн вывода инструментов

Обрезка истории разбирается со старым хламом, и это хорошо. Но представьте, что один-единственный grep вернул пять тысяч строк. Ущерб уже нанесён: модель проглотила простыню, потащит её ещё несколько шагов подряд, и только потом pruning сжалится. Дешевле не пускать простыню на порог вообще.

Проще говоря, потолок на выходе инструмента - это профилактика, а обрезка истории - уборка по факту. Нормальный harness делает и то, и другое, но именно профилактика экономит нервы.

ЧТО ПОЛУЧИТСЯ У всех трёх инструментов появится честный потолок: у read - 500 строк, у grep - 50 совпадений, у bash - 5000 символов, причём хвост, а не голова. А если вывод обрезали, модель прочитает об этом отдельную строку и сможет сузить запрос вместо того, чтобы врать с уверенным лицом.

Слова, которые встретятся

  • Потолок вывода (output cap) - жёсткий предел на размер ответа инструмента. Не вежливая просьба, а именно предел: код сам режет лишнее перед возвратом.
  • Сообщение об обрезке - честная приписка вроде «… (обрезано, показаны последние 5000 символов)». Без неё модель уверена, что видела файл целиком, и делает выводы по половине картины - с тем самым непробиваемым спокойствием, за которое мы все так любим языковые модели.

Быстрый путь

  1. Проверить, что у read и grep лимиты уже есть (модуль 1) и сообщение об обрезке на месте.
  2. В tools_bash.py добавить потолок 5000 символов с сохранением хвоста.
  3. Прогнать «жирный» поиск и ls -laR.

Какие файлы трогаем

Файл Что делать
tools_bash.py Править. Потолок stdout + сообщение об обрезке.
main.py (read, grep) Проверить лимиты; дописать суффикс, если его ещё нет.

Таблица потолков

Tool Потолок Зачем так
read 500 строк Большинство файлов хватает; огромный - через offset/limit
grep 50 совпадений 50 ответов уже ответ; 500 - свалка
bash 5000 символов Обычный вывод влезает; ls -laR - нет, и не надо

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

Шаг 1. Bash: хвост, не голова

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

В tools_bash.py найдите место после sandbox.exec. Строку return result["stdout"] or "(нет вывода)" замените целиком (не оставляйте старый return ниже):

tools_bash.py - вместо старого return

result = await sandbox.exec(command)
MAX_BASH_CHARS = 5000
stdout = result["stdout"] or "(нет вывода)"
if len(stdout) > MAX_BASH_CHARS:
    stdout = (
        stdout[-MAX_BASH_CHARS:]
        + f"\n... (обрезано, показаны последние {MAX_BASH_CHARS} символов)"
    )
return stdout

Шаг 2. Read и grep почти готовы

Здесь работы меньше, чем кажется. Если в модуле 1 вы поставили MAX_LINES = 500 и «первые 50 совпадений», половина урока у вас уже сделана. Осталось проверить, что при обрезке наружу уходит внятная фраза, а не молчаливо укороченный текст. Для grep это выглядит так:

... (87 всего, показаны первые 50)

Увидев такую приписку, модель обычно ведёт себя разумно: сужает glob или уточняет паттерн. А вот без приписки она радостно решит, что совпадений ровно пятьдесят, и построит на этом целую теорию.

КОНТРАКТ ОБРЕЗКИ Для любого инструмента с непредсказуемым выводом держите в голове три правила. Потолок должен существовать. Модель должна видеть, что вывод обрезали и насколько сильно. И должен быть способ добрать остальное: offset с limit, более узкий glob, уточнённый паттерн. Тихая обрезка без сообщения хуже, чем полное отсутствие лимита, потому что превращает честную нехватку данных в тихую дезинформацию.
ЗА ВСЁ НАДО ПЛАТИТЬ: ЛИШНИЕ ВЫЗОВЫ Файл на две тысячи строк теперь придётся читать в четыре захода вместо одного. Это нормальная цена: четыре коротких чтения обойдутся дешевле одной простыни, которая будет отравлять контекст до самого конца сессии.

Проверьте

uv run python main.py . "Найди все import в проекте"
uv run python main.py . "Выполни: ls -laR"

На первой команде grep должен упереться в полсотни совпадений и честно доложить, сколько их было всего. На второй, если проект не совсем пустой, рекурсивный листинг перевалит за потолок, и в ответе bash вы увидите хвост вывода с припиской про обрезку.

Готово, если:

  • read режет по 500 строкам с понятным хвостом
  • grep режет по 50 совпадениям и пишет total
  • bash режет stdout по 5000 символам, оставляя хвост
  • Ни один tool не отдаёт бесконечный вывод в контекст