tausik symbol — определение, а не адрес

Обычный путь к чужой функции стоит двух вызовов: grep, чтобы найти, и чтение файла, чтобы посмотреть. tausik symbol <имя> отвечает одним: путь и строка, тело определения и список тех, кто его зовёт.

EN mirror: /docs/symbol-index.md.

Откуда это взято

Из Graft — слоя контекста для агентов. Переносима его ДЕТЕРМИНИРОВАННАЯ половина: граф символов строится разбором исходников без всякой модели, а запрос возвращает исходный текст ВНУТРИ ответа, чтобы файл не пришлось открывать следом. Graft написан на TypeScript и стоит на tree-sitter; здесь Python и ast, потому что это то, что проект может нести без зависимостей.

Слой пояснений, который у Graft пишет модель, сознательно НЕ переносится: он требует ключа, сети и денег, а измеримая часть выигрыша лежит в детерминированной половине.

Зачем — замер, а не ощущение

Смена #233, восемь расшифровок, нагрузка результатов инструментов 4 826 406 символов:

Что	Доля
Навигация по коду по ИМЕНИ инструмента (Read, Grep, Glob, ToolSearch)	9.6%
grep/sed/find/ls внутри Bash — 1192 вызова по 1501 символу	37.1%
Разведка по коду на самом деле	около 47%

Первый счёт говорил «не стоит труда»: потолок выигрыша около 2.7% роста контекста. Счёт по тому, что команды ДЕЛАЮТ, перевернул вывод — половина разведки здесь носит имя Bash. Это решение #335 в новом месте: проверяй факт, а не наличие имени.

Что даёт замер после постройки

25 случайных функций длиной от 8 строк:

Способ	Вызовов	Символов
grep + sed	2	30 517
symbol, без вызывающих	1	29 442 (−3.5%)
symbol, с вызывающими	1	34 686 (+13.7%)

Выигрыш в ВЫЗОВАХ, а не в размере ответа. Это и есть та экономия, которую определяет решение #338: каждый вызов пере-отправляет весь разговор, и базовая линия проекта оценивает вызов в 266 645 токенов контекста. Лишние 13.7% покупают список вызывающих — вопрос, который иначе стоил бы третьего вызова.

Числа Graft (42% токенов, 46% вызовов) сюда НЕ переносятся: они сняты на других репозиториях. Совпадение по вызовам — совпадение, а не заимствование.

Как пользоваться

.tausik/tausik symbol tags_unmoved            # определение + вызывающие
.tausik/tausik symbol Holder.method           # метод класса
.tausik/tausik symbol answer --lines 20       # короче тело
.tausik/tausik symbol build_index --no-callers  # без обхода дерева, быстрее

Границы, названные явно

• Индекс ВЫВОДИТСЯ из дерева и никогда не правится руками. Он строится при каждом запросе (13 199 символов за 1.2 с), поэтому устареть не может. Реестр символов, поддерживаемый вручную, сгнил бы так же, как гнил здесь любой другой.
• Вызывающие ищутся ПО ИМЕНИ. Две функции с одинаковым именем дают один список: разрешение требует вывода типов, которого ast не делает. Список, который об этом говорит, лучше списка, который молча выбирает одну.
• Индексируются scripts, bootstrap, tests, harness. Символ вне их — вне индекса по построению, и отказ говорит об этом, а не молчит.
• Исходники РАЗБИРАЮТСЯ, а не импортируются. Импорт исполнил бы код каждого модуля дерева на этапе индексации.
• Ответ ограничен по длине, и обрезка называется. Молчаливая обрезка учит открывать файл всё равно — а это плата дважды.