istok

istok index, search и graph

Просмотр и перестройка локального индекса кода, поиск по репозиторию и исследование символов и их связей.

Istok ведёт локальный индекс репозитория каждого проекта. Агенты через MCP находят по нему нужный код, и каждое взятие задачи добавляет найденный в нём код в контекст. Эти команды дают доступ к тому же индексу, чтобы посмотреть на него и разобраться с проблемами. Обычно управлять им не нужно.

Команды

istok index status
istok index rebuild

istok search QUERY [--limit N]

istok graph symbol NAME [--limit N]
istok graph neighbors NAME [--kind KIND] [--limit N]
istok graph path FROM TO [--max-depth N] [--limit N]

Все команды работают с проектом, в котором находится текущая директория, и принимают --json и --database PATH.

Автоматическая актуальность

Istok проверяет, актуален ли индекс, каждый раз, когда он используется:

  • когда вы запускаете istok search или читаете граф;
  • когда агент берёт задачу в работу и Istok готовит для запуска контекст кода.

Если репозиторий изменился, Istok сначала обновляет индекс. Устаревший индекс никогда не выдаётся за актуальный: если подготовить пригодный индекс не удалось, поиск завершается ошибкой, а обычное взятие задачи не создаёт запуск — вместо того чтобы вернуть устаревшие результаты.

istok init строит первый индекс. Проект, зарегистрированный через MCP, получает первый индекс, когда поиск по коду понадобится впервые. Отдельного шага index update нет.

Что попадает в индекс

В Git-репозитории Istok индексирует отслеживаемые файлы и неотслеживаемые файлы, которые Git не игнорирует. Он учитывает вложенные .gitignore и .git/info/exclude. Вне рабочего дерева Git он обходит файловую систему с игнорированием по правилам Git.

Исключения только для Istok добавляйте в файл .istokignore в репозитории. Он может только добавлять исключения — вернуть файлы, которые игнорирует Git, он не может.

Istok всегда пропускает:

  • файлы .env и .env.*;
  • бинарные файлы и файлы, не являющиеся корректным текстом UTF-8;
  • файлы больше 512 KiB;
  • кэши зависимостей, результаты сборки и скрытые директории систем контроля версий.

Файлы с неизвестным расширением индексируются как обычный текст, если проходят эти проверки.

index status

istok index status

Показывает текущий индекс и его состояние, ничего не обновляя и не перестраивая. Начинайте с этой команды, когда поиск или взятие задач не работают.

index rebuild

istok index rebuild

Принудительно строит новый индекс. Это инструмент для ремонта и диагностики, а не шаг перед обычной работой. Новое поколение индекса становится активным только после успешной подготовки.

istok search "order not found"
istok search "order not found" --limit 20

Возвращает результаты, упорядоченные по релевантности (по умолчанию 10): место в репозитории, совпавший фрагмент, оценку и объяснение, почему результат подошёл, — например точное имя символа, идентификатор, путь или лексическое совпадение.

Ищите, когда знаете, какой текст, идентификатор или поведение вам нужны.

graph

Граф кода охватывает Go, TypeScript (включая TSX) и JavaScript (включая JSX). Файлы на других языках всё равно индексируются для поиска. Используйте граф, когда знаете символ и хотите увидеть, как он связан с остальным кодом.

Найти символ

istok graph symbol OrderService
istok graph symbol orders.OrderService --limit 10

Принимает точные короткие и полные (qualified) имена. По умолчанию возвращает до 20 символов.

Соседи

istok graph neighbors OrderService
istok graph neighbors OrderService --kind calls --limit 20

--kind можно повторять; виды связей — contains, imports, calls, references, inherits и implements. В результатах указана связь и место, где она найдена. По умолчанию — до 20 соседей.

Путь между символами

istok graph path OrderHandler OrderRepository
istok graph path OrderHandler OrderRepository --max-depth 6 --limit 10

Находит пути ограниченной длины между двумя символами. По умолчанию: глубина 6, 10 путей.

Неполный граф

Если часть файлов не может дать полную структурную информацию, Istok оставляет поиск доступным и сообщает, что граф неполный (degraded), а не делает вид, что он полный. Проверьте это через istok index status; если проблема не уходит, а граф вам нужен, выполните istok index rebuild.

Вывод JSON

Результаты поиска используют формат istok.retrieval.v1, а результаты графа — istok.graph.v1, каждый внутри версионированной обёртки Istok. См. Вывод JSON.

Справка

istok index --help
istok search --help
istok graph --help