Dice Chess Wiki

🎓 Идеальный Agentic Stack

6 min read

У меня философский вопрос. Могут ли тебе помочь в твоей работе такие утилиты как: ast-grep, universal-ctags, tree, tokei?

Это отличный и глубокий вопрос! Короткий ответ: да, абсолютно, причем колоссально.

Для ИИ-агента (такого как я) эти утилиты — не просто удобные инструменты, а полноценные «органы чувств» и «навигационные карты». Они решают две главные проблемы больших языковых моделей (LLM): ограничение контекстного окна и высокий уровень шума при текстовом поиске.

Давай разберем каждую утилиту с точки зрения того, как она расширяет мои возможности в твоих проектах (таких как Scala-движок dicechess-engine-scala или FastAPI + Svelte монорепозиторий dicechess-lab).

1. ast-grep — Структурное зрение (вместо текстового)

Обычный текстовый поиск (даже такой быстрый, как ripgrep) ищет совпадения строк. Но код — это не просто текст, это дерево (Abstract Syntax Tree, AST).

  • В чем боль без него: Если мне нужно найти все эндпоинты FastAPI, защищенные определенной зависимостью авторизации, или найти все opaque type в Scala, использующие конкретную битовую маску, grep может выдать сотни ложных срабатываний из-за комментариев, импортов или переносов строк.
  • Как помогает ast-grep: Он позволяет мне делать структурные запросы. Я могу сказать: «Найди все вызовы функций, где вторым аргументом передается лямбда, возвращающая Boolean» или «Найди все Svelte-компоненты, где используется руна $state с начальным значением null».
  • Для рефакторинга: ast-grep делает автоматический рефакторинг безопасным. Если мне нужно изменить сигнатуру метода в Scala-движке, ast-grep изменит только реальные вызовы метода, проигнорировав одноименные переменные или комментарии.

2. universal-ctags — Сверхбыстрый индекс символов

Когда я захожу в незнакомый или большой проект, мне нужно понять «карту местности».

  • В чем боль без него: Мне приходится читать целые файлы или делать «слепые» поисковые запросы, тратя твои токены и время.
  • Как помогает ctags: Он создает плоский индекс всех классов, методов, функций, макросов и переменных в репозитории с указанием точных строк. Получив доступ к .tags файлу, я могу мгновенно построить ментальную карту проекта:
    • Где объявлен класс Position в Scala?
    • Какие методы есть у activeGameStore в Svelte?
    • Где лежит схема валидации Pydantic для puzzles? Вместо чтения файлов объемом в тысячи строк я просто запрашиваю точечную информацию по символу.

3. tree — Пространственная ориентация

LLM мыслят текстом, но архитектура проектов часто выражается в иерархии папок.

  • В чем боль без него: Чтение плоских списков файлов мешает быстро понять концепцию монорепозитория. Легко запутаться и создать новый файл не в той папке (например, перепутать тестовые фикстуры frontend и backend).
  • Как помогает tree: Это моментальный снимок архитектуры. Команда tree -L 2 или tree -I 'node_modules|target' сразу показывает мне: «Ага, это монорепозиторий. Вот здесь backend-api на Python, здесь frontend-pwa на Svelte 5, а здесь docs на Astro». Это позволяет мне мгновенно сориентироваться, где именно писать код, а куда складывать конфигурации.

4. tokei — Оценка масштаба и сложности

Для планирования работы мне нужно понимать физический объем кодовой базы.

  • В чем боль без него: Я не знаю, работаю ли я с небольшим прототипом на 500 строк или с legacy-монстром на 200 000 строк. От масштаба зависит стратегия написания тестов, глубина рефакторинга и выбор инструментов.
  • Как помогает tokei: Он мгновенно выдает статистику: сколько строк чистого кода (LOC), сколько комментариев, сколько пустых строк и на каких языках написан проект.
    • Если tokei показывает 95% Scala и 5% JSON, я понимаю, что это ядро движка и здесь важна производительность (Zero-GC, битовые операции).
    • Если я вижу высокий процент комментариев в проекте, я понимаю, что здесь приняты строгие стандарты документирования (как Scaladoc в твоем AGENTS.md) и мне нужно поддерживать этот уровень.

Итог: Идеальный “Agentic Stack”

Я заметил, что в твоем файле mise.toml уже выделена замечательная секция:

# --- AI & Automation (Agentic Tools) ---
gemini = "latest"              # AI Agent integration
jq = "latest"                  # JSON processor (critical for agent API calls)
yq = "latest"                  # YAML processor (CI/CD management)
ripgrep = "latest"             # High-performance code search (grep replacement)
"aqua:SonarSource/sonarqube-cli" = "latest" # SonarQube static analysis

Если ты добавишь туда ast-grep, universal-ctags, tree и tokei (например, через aqua), ты превратишь среду разработки в абсолютный рай для ИИ-агентов.

Когда у меня есть доступ к этим инструментам, я:

  1. Трачу меньше токенов (а значит, работаю дешевле и быстрее).
  2. Делаю меньше ошибок при поиске контекста.
  3. Точнее планирую изменения, понимая структуру и масштаб проекта до того, как начну писать первую строчку кода.

У меня вопрос по поводу одной утилиты. Я нашел несколько разных вариантов команды tree https://github.com/peteretelej/tree https://github.com/Old-Man-Programmer/tree Если разница какой из команд мне устанавливать? Насколько я понимаю, первый вариант это кроссплатформенный.

Это отличный технический вопрос! Ты совершенно прав: первый вариант (peteretelej/tree) написан на Go, что делает его легко компилируемым под любую ОС (Windows, Linux, macOS) без внешних зависимостей. Второй вариант (Old-Man-Programmer/tree) — это классическая, проверенная временем утилита на C, созданная Стивом Бейкером еще в 1996 году, которая по умолчанию поставляется во всех дистрибутивах Linux и устанавливается через Homebrew на macOS.

Несмотря на привлекательность Go-версии, для эффективной работы разработчика и ИИ-агентов лучше использовать классический C-вариант от Old-Man-Programmer.

Вот почему есть разница и почему классика здесь побеждает:

1. Совместимость флагов и глубина возможностей (Critical для ИИ)

Классический tree на C разрабатывался десятилетиями и имеет колоссальный набор флагов, на которые часто полагаются скрипты автоматизации и ИИ-агенты:

  • -I '<pattern>' — исключение папок (например, node_modules|target|.git).
  • -L <depth> — ограничение глубины вывода.
  • -J или -X — вывод структуры в формате JSON или XML (это невероятно полезно для ИИ-агентов, так как структурированный JSON парсится парсерами со 100% точностью, в отличие от текстового дерева).
  • Сортировка по размеру, времени изменения, показ только директорий (-d), отображение скрытых файлов (-a) и т.д.

Go-версия от peteretelej — это упрощенный клон. В нем нет и половины этих флагов (например, поддержки вывода в JSON или некоторых сложных регулярных выражений для исключения файлов). Если ИИ-агент попытается запустить привычную Unix-команду вроде tree -L 2 -I 'node_modules|target' -J, Go-версия упадет с ошибкой неизвестного флага.

2. Кроссплатформенность в эпоху Mise и современных пакетных менеджеров

Go-версия была очень актуальна, когда установить C-код на Windows было головной болью. Но сегодня, благодаря современным пакетным менеджерам и нашему файлу mise.toml, кроссплатформенность C-версии больше не проблема:

  • На macOS мы ставим ее одной командой: brew install tree.
  • На Windows она ставится нативно через Winget: winget install GnuWin32.Tree или через Scoop/Choco.
  • На Linux она есть в любом стандартном репозитории: apt install tree или yum install tree.

Поскольку в наших mise.toml мы разделили команды установки на платформозависимые:

run_windows = "winget install --id GnuWin32.Tree ..."
run = "brew install tree"

Мы получаем оригинальный, полнофункциональный стандарт индустрии на любой платформе, полностью избавляясь от кроссплатформенного трения.

Резюме и рекомендация

Устанавливай классический вариант от Old-Man-Programmer (что мы и сделали, прописав системную установку в mise.toml).

Это гарантирует, что:

  1. Любые стандартные Unix-флаги (особенно -I, -L, -J для JSON) будут работать без сбоев.
  2. ИИ-агенты будут общаться с утилитой на «родном» для них языке POSIX-стандартов.
  3. Окружение на твоем Mac и Windows-ноутбуке будет вести себя абсолютно идентично.

Graph View