Проект «Разведчик»: агент, который знает ваш репозиторий

Модуль собран из деталей — пора пустить их в дело. «Разведчик» — первый настоящий житель devbuddy: утилита командной строки, которой задаёшь вопрос по репозиторию, а она сама решает, где искать, что открыть и когда достаточно. Это ещё не ревьюер (ему нужен GitHub API из следующего модуля), но уже агент: петля, инструменты, бюджет памяти — всё ваше, рабочее.

Задача

Утилита scout.py:

java

python scout.py "где в этом репо валидируется email?"

Основная функциональность

• Вопрос принимается аргументом командной строки; корень репозитория — текущая папка (или флаг --root).

• Внутри — ваш конвейер: make_tools + петля + сжатие истории (как в hard-задаче, но лимиты щедрее: 6 шагов, бюджет промпта 1500 токенов).

• В конце печатает человеку: ответ модели и, для прозрачности, число шагов и примерную стоимость прогона в токенах (сумма estimate_tokens по всем промптам — ваш tokens.py в деле).

• Живой режим — при наличии ключа (LLMClient); без ключа честно сообщает, что нужен ключ, и выходит с кодом 1.

Пример работы

java

$ python scout.py "где обрабатывается деление на ноль?"
Ответ: src/calc.py:14, функция divide — там try/except ZeroDivisionError
Шагов: 3, оценка расхода: 2140 токенов

Приёмка

1. Фикстура. Скачайте тестовый репозиторий из условия (три файла из hard-задачи плюс пара своих) и ответьте на два вопроса: «где валидируется email?» и «где бросается ValueError?». Ответы содержат имя файла.

2. Свой репозиторий. Задайте три вопроса по devbuddy (например: «где считается стоимость месяца?»). Ответы осмысленные, путь к файлу — верный.

3. Экономика. Для прогона из 3–4 шагов посчитана оценка токенов и выведена в отчёт.

4. Устойчивость. Вопрос «про жизнь и вообще» не роняет утилиту: лимит шагов отрабатывает, агент отвечает честно («не нашёл»), exit code 0.

Ограничения и дух проекта

• Только модули, написанные в этом модуле: loop.py, tools.py, history.py, tokens.py, llm.py. Новых зависимостей нет.

• Инструменты только читающие: list_dir, read_file, search. Никаких write/delete — разведчик смотрит, не трогает.

• Промпт шага — ваш build_prompt; если агент циклится, чинится это правкой промпта (подсказка стратегии), а не кода.

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