Graphify — превращаем папку с файлами в граф знаний для ИИ-агентов

Graphify строит из кода, документации и других файлов граф знаний, по которому ИИ-ассистент может искать связи между сущностями, объяснять узлы и находить пути. По официальной документации, репозиторию и журналу релизов, проверенным 4 сентября 2026 года, актуальная на эту дату версия — v0.9.53.

Содержание

1. Что Graphify создаёт
2. Как устроено извлечение
3. Какие файлы поддерживаются
4. Установка и первый граф
5. Запросы и обновление
6. Проверка результата
7. Полезные сценарии
8. Приватность и безопасность
9. Ограничения
10. Ссылки

Что Graphify создаёт

Graphify — open-source-инструмент Graphify Labs. В репозитории указаны лицензии Apache 2.0 и MIT. Он превращает проект или выбранную папку в граф: узлами могут быть файлы, классы, функции, понятия и другие сущности, а рёбрами — вызовы, импорты, наследование, ссылки и смысловые связи.

Результат сохраняется в каталоге graphify-out/:

• graph.json — машиночитаемый граф для CLI и MCP;
• graph.html — интерактивная визуализация;
• GRAPH_REPORT.md — обзор ключевых узлов, сообществ и неожиданных связей.

По документации, каждое ребро получает метку EXTRACTED, INFERRED или AMBIGUOUS. Они помогают отличать отношения, явно найденные в источнике, восстановленные Graphify и неоднозначные связи. Метка не заменяет проверку исходного файла, особенно перед архитектурным решением.

Как устроено извлечение

Для программного кода Graphify использует локальный разбор синтаксического дерева (AST) через Tree-sitter. Такой проход детерминирован и не требует отправлять код в модель.

Документы и медиа обрабатываются отдельным семантическим проходом. Markdown, PDF, изображения, аудио и видео могут анализироваться моделью ассистента; при извлечении без ассистента используется настроенный API-бэкенд. Свойство «локально» поэтому относится прежде всего к AST-разбору кода. При семантической обработке содержимое может передаваться провайдеру модели.

После извлечения Graphify разрешает межфайловые связи и группирует узлы в сообщества. Для кластеризации репозиторий описывает Leiden; при отсутствии нативной привязки используются запасная реализация graspologic, а затем NetworkX Louvain.

Какие файлы поддерживаются

Актуальный репозиторий перечисляет десятки языков и форматов. Основные группы:

• код: Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, Kotlin, PHP, Swift, Ruby, SQL и другие языки;
• документация: Markdown, MDX, reStructuredText, HTML, YAML и обычный текст;
• проектные данные: конфигурации MCP, pyproject.toml, go.mod, pom.xml, файлы решений и проектов;
• документы: PDF, DOCX и XLSX;
• изображения: PNG, JPEG, WebP и GIF;
• аудио и видео: MP3, WAV, MP4, MOV и другие форматы.

Часть возможностей поставляется как дополнительные зависимости. Например, для PDF, Office-файлов, видео и MCP-сервера нужны соответствующие extras пакета graphifyy; для отдельных языков и экспортов также предусмотрены дополнительные зависимости.

Установка и первый граф

Минимальное требование — Python 3.10+. Официальный пакет в PyPI называется graphifyy с двумя буквами y; команда после установки называется graphify.

Рекомендуемый вариант:

uv tool install graphifyy
graphify install

Альтернативы:

pipx install graphifyy
# или
pip install graphifyy

Команда graphify install регистрирует skill. Для явного выбора платформы используйте:

graphify install --platform codex
graphify install --platform claude
graphify install --platform cursor

Для установки только в текущий репозиторий добавьте --project:

graphify install --project --platform codex

После установки откройте папку проекта в поддерживаемом ассистенте и запустите построение графа:

/graphify .

В Codex skill вызывается как $graphify, а в PowerShell следует использовать graphify . без начального слеша.

Подключение по MCP

MCP (Model Context Protocol) даёт ассистенту структурированный доступ к уже построенному графу. Для локального сервера установите дополнительную зависимость и используйте транспорт stdio:

uv tool install "graphifyy[mcp]"
python -m graphify.serve graphify-out/graph.json

Для общего HTTP-сервера:

python -m graphify.serve graphify-out/graph.json --transport http --port 8080

При HTTP-транспорте сервер по умолчанию слушает 127.0.0.1. Если его нужно открыть за пределами локального компьютера, задайте API-ключ и сетевые ограничения:

export GRAPHIFY_API_KEY="<YOUR_API_KEY>"
python -m graphify.serve graphify-out/graph.json --transport http --host 0.0.0.0 --api-key "$GRAPHIFY_API_KEY"

Запросы и обновление

Готовый graph.json можно читать через CLI:

graphify query "что связывает авторизацию с базой данных?"
graphify path "UserService" "DatabasePool"
graphify explain "RateLimiter"

• query ищет подходящие узлы и возвращает релевантный подграф с путями и ссылками на строки исходников;
• path находит кратчайший путь между двумя узлами;
• explain описывает узел, его расположение и соседние связи.

У graphify query стандартный бюджет вывода составляет 2000 токенов. Его можно изменить флагом --budget. Для исследования одной цепочки вместо широкого обхода предусмотрен --dfs.

После изменения корпуса используйте инкрементальное обновление:

/graphify . --update

Для кода можно установить Git-хуки:

graphify hook install

Они автоматически перестраивают AST-часть после коммита и переключения ветки. После git pull или git merge официальный workflow рекомендует отдельно выполнить:

graphify update .

Изменившиеся документы и другие семантические источники обновляйте через skill с --update, поскольку их слой обрабатывается отдельно от AST-кода.

Проверка результата

Материал основан на официальных источниках; описанные команды в рамках подготовки справочника не запускались. После построения графа проверьте результат самостоятельно:

1. При обычном запуске без --no-viz убедитесь, что существуют graphify-out/graph.json, graphify-out/graph.html и graphify-out/GRAPH_REPORT.md.
2. Откройте graph.html и найдите несколько известных сущностей проекта.
3. Выполните graphify explain для класса или функции, расположение которых вам известно.
4. Запустите graphify path для двух заведомо связанных компонентов.
5. Сверьте указанные файлы и строки с исходным кодом.
6. Просмотрите связи INFERRED и AMBIGUOUS в критичных участках.
7. После изменения файла выполните обновление и убедитесь, что новый узел или связь появились в графе.

Наблюдаемый признак успеха: команды открывают нужный graph.json, находят ожидаемые сущности и показывают проверяемые пути к исходным файлам.

Полезные сценарии

Навигация по большому репозиторию

Задача: понять поток, который проходит через несколько файлов и модулей.

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

Действия: постройте граф, задайте вопрос через graphify query, затем уточните цепочку с помощью path и explain.

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

Ограничение: для небольшого проекта прямой просмотр файлов может быть проще.

Аудит архитектуры и последствий изменений

Задача: понять зависимости центрального класса, импорта или сервиса.

Условие: нужно оценить соседние компоненты и путь до целевого сервиса.

Действия: найдите сущность через explain, изучите её связи и проверьте путь через path.

Результат: видны узлы с высокой степенью связности и межмодульные пути.

Ограничение: граф остаётся вспомогательной картой. Перед изменением кода проверяйте найденные отношения в исходниках, особенно если они помечены как INFERRED.

Смысловая карта базы знаний

Задача: найти связи и пробелы в архиве Markdown, PDF и заметок.

Условие: архив регулярно пополняется, а для нужных форматов установлены дополнительные зависимости.

Действия: постройте граф, изучите сообщества, изолированные узлы и неожиданные связи в GRAPH_REPORT.md и graph.html.

Результат: появляются кандидаты на внутренние ссылки, отдельные материалы и пересмотр рубрик.

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

Сопоставление с ручным контентным графом

Задача: сравнить редакторскую структуру сайта с отношениями, извлечёнными из содержания.

Условие: у сайта уже есть ручная разметка тегами, описаниями и внутренними ссылками.

Действия: сопоставьте эту разметку с узлами и сообществами Graphify.

Результат: можно заметить темы без собственной страницы, непроставленные внутренние ссылки и расхождения между рубриками и фактическими кластерами. Для методологии такого сравнения см. «Контентный граф — методология управления контентом через связи, а не рубрики».

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

Приватность и безопасность

• AST-разбор кода выполняется локально и не требует LLM или API-вызовов.
• Семантическая обработка документов и медиа может передавать содержимое выбранному провайдеру модели.
• graph.json, отчёт и визуализация по умолчанию сохраняются локально в graphify-out/.
• При HTTP-транспорте MCP-сервер по умолчанию привязан к 127.0.0.1.
• При публикации MCP-сервера через 0.0.0.0 используйте --api-key и сетевые ограничения.
• Журнал запросов отключён по умолчанию. Его включение создаёт локальную запись вопросов и пути к корпусу.

Ограничения

• Полнота графа зависит от поддержки языка и качества разрешения межфайловых связей. Changelog v0.9.53 продолжает фиксировать ошибки разрешения для разных языков.
• Качество семантических узлов зависит от модели и выбранного режима, включая более глубокий режим анализа.
• Инкрементальное обновление нужно встроить в рабочий процесс: после слияния или получения изменений требуется graphify update ..
• Большие графы требуют больше памяти и могут быть неудобны для полной визуализации.
• Стандартный предел загрузчика для graph.json составляет 512 МиБ, то есть 536 870 912 байт. Его можно увеличить, например:

GRAPHIFY_MAX_GRAPH_BYTES=700MB graphify query "вопрос"

Переменная принимает обычное число байт, а также значения в MB или GB по основанию 1024.

Для graphify export html в официальном обсуждении описан автоматический переход к агрегированному представлению сообществ при превышении лимита. Для других форматов экспорта может потребоваться явное увеличение лимита. Перед использованием проверьте поведение установленной версии через graphify --help.

Ссылки

• Официальный сайт Graphify
• Документация CLI
• Официальный репозиторий
• Changelog
• Релизы GitHub
• Обсуждение лимита graph.json

Если вы планируете использовать Graphify для рабочего архива или закрытого репозитория, заранее определите границы корпуса, режим обработки документов и правила проверки выведенных связей.

Следующий шаг

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

Связанные материалы

• Блог: «Почему личный сайт — это не визитка, а основа всей публичной системы»

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov