Построение кодирующего агента для контекста в 8 тыс. токенов: разделение планировщика/исполнителя, бюджетирование токенов и параллельное выполнение

Большинство ИИ-инструментов для кодирования предполагают модели с 200 тыс. токенов, но если вы используете локальные LLM через Ollama, LM Studio или бесплатные API вроде Groq или OpenRouter, вам приходится довольствоваться ~8 тыс. токенами. Этого не хватит на целый проект — едва ли достаточно для одного большого файла. Один разработчик потратил недели на создание CLI-агента, рассчитанного на это ограничение, и поделился практическими выводами.

Основная архитектура: разделение на planner и executor

Агент никогда не показывает LLM весь проект. Вместо этого работа делится на три роли:

• Planner: видит только легковесную карту проекта (Markdown-сводки по каждой папке, всего ~300–500 токенов) плюс запрос пользователя и выдает список задач.
• Executor: за один вызов видит ровно один файл и одну задачу — никогда не два файла вместе.
• Orchestrator: чистый код (без LLM), который строит граф зависимостей из списка задач и решает, какие задачи можно выполнять параллельно, а какие — последовательно.

Это превращает рефакторинг нескольких файлов из проблемы контекстного окна в проблему планирования. Planner'у не нужно видеть код, а executor за раз видит только ограниченный объем кода.

Контроль токенов в коде

Каждый вызов LLM проходит проверку canFit(), которая измеряет системный промпт + зарезервированные выходные токены + память + фактический код. Если код не помещается, агент переключается на пофайловый индекс строк (создается один раз для файлов длиннее ~150 строк) и извлекает только нужную секцию.

Бюджет для 8192 токенов:

Системный промпт + инструкции: ~1000
Зарезервировано на ответ: ~2000
Краткосрочная память (4 записи): ~360
Доступно для кода: ~4800 (около 140–190 строк)

Если бюджет ограничен, сначала отбрасывается контекст папок, затем память, и только потом — часть кода.

Параллельное выполнение для ускорения

Поскольку каждый executor видит только один файл, независимые правки в разных файлах выполняются одновременно. Рефакторинг 5 файлов завершается примерно за время самого долгого изменения. Граф зависимостей (строится в коде из списка задач planner'а) определяет порядок.

Болевые точки и их устранение

• Запросы в стиле вопросов перезаписывают файлы: вопрос «сколько строк в X?» заставлял executor'а записывать ответ в файл. Исправлено добавлением поля action_type: "query" в вывод planner'а, которое обрабатывается кодом, не затрагивающим диск.
• Устаревшие карты проекта ведут к неправильным маршрутам: если пользователь упоминал переименованный файл, отсутствующий в карте, planner молча перенаправлял на ближайшее совпадение. Теперь orchestrator проверяет, существуют ли упомянутые пути к файлам на диске, и выдает четкую ошибку, если их нет.
• Markdown-ограждения в выводе executor'а: маленькие модели оборачивают код в тройные обратные кавычки, даже если им сказано не делать этого. Исправлено: удалять их при постобработке, а не бороться с промптом.
• Стоимость токенов памяти: постоянная память добавляет ~80–90 токенов на запись. При нехватке бюджета сначала отбрасывается контекст папок, затем память, прежде чем урезать сам код.

Открытые вопросы

Выдержит ли разделение на planner/executor кодовые базы из более чем 50 файлов — граф зависимостей остается управляемым, но карта проекта начинает стоить реальных токенов. Сейчас сначала отбрасывается контекст папок, но при глубоких правках контекст теряется. Реализация опубликована в открытом доступе, если хотите покопаться.