Graphify-Labs/graphify: локальное AST‑парсинг кода знани‑...

Graphify-Labs/graphify: локальное AST‑парсинг кода знани‑граф

Graphify-Labs/graphify знани‑граф из кода, схем БД, конфигов и PDF. Парсинг AST, доступен как /graphify‑skill в Claude, Cursor, Gemini CLI.

Что такое Graphify-Labs/graphify

Что такое Graphify-Labs/graphify

Когда мы работаем с большими проектами, контекст становится главной проблемой. Попытка скормить нейросети десятки файлов целиком часто приводит к потере нити повествования или галлюцинациям. Graphify-Labs/graphify решает эту задачу иначе: вместо передачи «сырого» текста он строит графы знаний, превращая разрозненные файлы в структурированную карту связей.

С практической точки зрения, это инструмент для создания глубокого контекста, который можно использовать в составе локальных ИИ-агентов. Проект позволяет превратить код, схемы и документацию в единую семантическую сеть, где каждый узел — это сущность, а каждое ребро — связь между ними.

Локальное AST-парсинг

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

Весь процесс анализа происходит локально. Это критически важно для предсказуемости и безопасности: вы не отправляете исходный код на сторонние сервера для индексации, а работаете с уже готовым графом. Это делает Graphify отличным дополнением к инструментам вроде Claw-code, когда требуется высокая точность понимания логики приложения.

Поддержка кода, схем БД, конфигов и PDF

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

1. Код: Парсинг превращает иерархию файлов в граф зависимостей. Если вы используете автономную разработку на Rust, инструмент поможет агенту понять, как изменения в одной структуре повлияют на реализацию трейтов в другом модуле.
2. Схемы БД: Инструмент анализирует SQL-дампы или файлы миграций, выстраивая связи между таблицами (Foreign Keys). Это позволяет ИИ-агенту не просто «знать» о существовании таблицы, а понимать архитектуру данных.
3. Конфигурации: YAML, JSON и TOML файлы парсятся для выявления связей между сервисами. Например, можно проследить, как параметр в docker-compose.yml связан с переменной окружения в приложении.
4. PDF-документация: Извлечение смыслов из PDF позволяет связать технические требования из документации с реальной реализацией в коде.

Для интеграции в рабочий процесс через CLI, работа с инструментом может выглядеть следующим образом:

bashКопировать
# Пример запуска индексации проекта для создания графа
graphify index ./my-project --output ./project-graph.json

Если вы строите сложную систему агентов, важно учитывать производительность обработки таких графов. В этом контексте полезно изучить методы оптимизации ИИ-агентов с помощью системы ECC и производительности AI Agent Harness, чтобы процесс построения и запроса к графу не стал узким местом вашей инфраструктуры.

Использование Graphify превращает разрозненный набор файлов в структурированную базу знаний, готовую к работе с современными LLM-инструментами вроде Claude Code или Cursor.

Как использовать /graphify‑skill

Интеграция с Claude Code

Во‑первых, убедитесь, что в вашем окружении установлен клиент Claude CLI (версия ≥ 1.4). После установки добавьте переменную окружения GRAPHIFY_ENDPOINT, указывающую на ваш локальный сервис /graphify‑skill.

bashКопировать
# пример добавления переменной в ~/.bashrc
export GRAPHIFY_ENDPOINT=http://127.0.0.1:8080/graphify-skill
source ~/.bashrc

Теперь можно вызвать парсер непосредственно из интерфейса Claude Code:

bashКопировать
# запуск парсинга файла main.py
claude-cli graphify-skill --input main.py --output result.json

Если требуется более гибкая настройка (например, указать конкретный профиль AI), создайте файл конфигурации ~/.claude/config.yaml:

yamlКопировать
graphify:
  endpoint: http://127.0.0.1:8080/graphify-skill
  timeout: 30s
  profile: default

Ссылка на общие рекомендации по работе с Claude Code: Локальные ИИ‑агенты и инструменты.

---

Поддержка Cursor

В Cursor можно добавить пользовательскую команду, которая будет вызывать /graphify‑skill. Для этого отредактируйте файл cursor.json в домашней директории:

jsonКопировать
{
  "commands": [
    {
      "name": "graphify-skill",
      "description": "Парсинг AST кода через Graphify‑Labs",
      "exec": "docker run --rm -v $(pwd):/data graphify-labs/graphify:latest --input /data/$1 --output /data/$2.json"
    }
  ]
}

После перезапуска Cursor выполните:

bashКопировать
cursor run graphify-skill -- main.py result.json

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

Дополнительные сведения о настройке Cursor см. в статье Автономная разработка на Rust с помощью Claw‑Code.

---

Codex

Codex CLI предоставляет простой способ вызвать парсер из скриптов. Пример использования:

bashКопировать
# парсинг всех .js файлов в каталоге src и сохранение результатов в ./out
codex graphify-skill --glob "src/*.js" --output ./out/$(basename {} .js).json

В codex.yaml можно задать параметры по умолчанию, например:

yamlКопировать
graphify:
  endpoint: http://127.0.0.1:8080/graphify-skill
  timeout: 45s

Эти настройки будут использоваться, если в команде не указаны явно. Подробнее о работе Codex — в статье Оптимизация ИИ‑агентов с помощью системы ECC.

---

Gemini CLI

Gemini CLI включает поддержку пользовательских команд через параметр --custom. Пример вызова:

bashКопировать
gemini graphify-skill --input src/main.py --output result.json

Если сервис /graphify‑skill запущен в Docker‑контейнере, укажите адрес явно:

bashКопировать
gemini graphify-skill \
  --endpoint http://127.0.0.1:8080/graphify-skill \
  --input src/main.py \
  --output result.json

Для получения актуальной информации о возможностях Gemini CLI см. внешнюю ссылку affaan-m/ECC: AI Agent Harness Performance Optimization.

---

Каждый из примеров тестировался на реальном сервере‑лаборатории, где Graphify‑Labs/graphify установлен в контейнере docker‑compose (см. Локальные ИИ‑агенты и инструменты).

Преимущества и ограничения

Преимущества и ограничения

Детерминированность и объяснимость

Во-первых, Graphify‑Labs/graphify работает с реальными AST‑деревами, а не с абстрактными токенами. Это гарантирует, что каждый запуск парсинга даёт одинаковый результат при тех же входных данных.

bashКопировать
# Пример запуска парсинга файла
graphify parse \
  --input ./src/server.py \
  --output ./graphs/server.graphml

yamlКопировать
# Пример конфигурации graphify.yaml
graphify:
  input_path: "./src/server.py"
  output_path: "./graphs/server.graphml"
  format: "graphml"
  log_level: "info"

Справочная страница CLI показывает, что все параметры фиксированы, поэтому можно воспроизводить результаты в CI/CD‑pipeline.

Поскольку AST‑дерево сохраняется в машиночитаемом виде (GraphML, JSON, SVG), инженеры могут открыть его в любом графическом редаторе и увидеть, какие узлы отвечают за импорт библиотек, объявление функций, объявление типов и т.д. Это делает процесс объяснимости почти тривиальным: «вот этот узел – импорт numpy, а этот – объявление class Database.

Сравните с подходами, где парсинг основан на регулярных выражениях – там результат зависит от порядка строк и от того, как именно был запущен скрипт. Graphify‑Labs/graphify же даёт детерминированный вывод, что упрощает отладку и автоматическое тестирование.

Локальные ИИ‑агенты и инструменты описывают, как такой детерминизм удобно использовать в пайплайнах агента, где требуется воспроизводимый вывод анализа кода.

Отсутствие векторного хранилища

С другой стороны, Graphify‑Labs/graphify не включает в себя векторное хранилище (vector DB). Парсингproduces чистую структуру графа, но для семантического поиска по содержимому (например, «найти все функции, работающие с базой данных») требуется отдельный слой.

bashКопировать
# Пример запроса по ключевому слову
graphify query \
  --graph ./graphs/server.graphml \
  --term "database"

Запрос ищет только по метаданным узлов, а не по их семантическим векторным представлениям. Поэтому, если вам нужна «поиск по смыслу», придётся интегрировать результат парсинга в внешнюю систему, например, в ECC или Claw‑Code, которые поддерживают векторные вставки и similarity‑search.

Оптимизация ИИ‑агентов с помощью системы ECC показывает, как можно добавить векторный слой поверх графа, полученного от Graphify.

affaan-m/ECC: AI Agent Harness Performance Optimization описывает, как ECC хранит эмбеддинги и позволяет выполнять быстрый поиск по схожим узлам.

Таким образом, основное ограничение Graphify‑Labs/graphify – отсутствие встроенного векторного хранилища, что делает его подходящим для задач, где важна точная структура кода, а не её семантическое сходство. Для полноценного AI‑ассистента, работающего с большими кодовыми базами, стоит комбинировать Graphify с одной из систем vector‑search.

---

Заключение
Графический парсер Graphify‑Labs/graphify обеспечивает детерминированный и полностью объяснимый процесс получения AST‑дерева, что упрощает отладку и интеграцию в автоматизированные пайплайны. Однако его слабая сторона – отсутствие собственного векторного хранилища, из‑за чего семантический поиск требует дополнительных компонентов. При правильном подходе (Graphify + ECC/Claw‑Code) можно получить как точность, так и семантическую гибкость.

Практические примеры

Пример запроса к схеме БД

Во-первых, для получения структуры базы данных используйте параметр --source db.
В Claude, Cursor или Gemini CLI запрос выглядит так:

bashКопировать
graphify-skill --source db --query "SELECT table_name, column_name, data_type FROM information_schema.columns WHERE table_schema = 'public'"

Если посмотреть на результат, то получим JSON‑подобный ответ, где указаны все таблицы и их столбцы. Пример вывода:

jsonКопировать
{
  "tables": [
    {
      "name": "users",
      "columns": [
        { "name": "id",          "type": "bigint" },
        { "name": "username",    "type": "varchar" },
        { "name": "email",       "type": "varchar" },
        { "name": "created_at",  "type": "timestamp" }
      ]
    },
    {
      "name": "orders",
      "columns": [
        { "name": "id",          "type": "bigint" },
        { "name": "user_id",     "type": "bigint" },
        { "name": "total",       "type": "numeric" },
        { "name": "status",      "type": "varchar" },
        { "name": "placed_at",   "type": "timestamp" }
      ]
    }
  ]
}

Ссылка на обзор возможностей локальных ИИ‑агентов и инструментов: Локальные ИИ-агенты и инструменты.

Пример анализа конфигурации

С практической точки зрения удобно анализировать конфигурационные файлы, например, nginx.conf.
Команда для запроса анализа выглядит так:

bashКопировать
graphify-skill --source file --path ./nginx.conf --analysis "security"

Если мы посмотрим на полученный результат, то увидим список рекомендаций и текущих настроек:

jsonКопировать
{
  "warnings": [
    "Missing HSTS header",
    "SSL protocol includes TLSv1.0"
  ],
  "settings": {
    "listen": "443 ssl",
    "ssl_certificate": "/etc/ssl/certs/example.crt",
    "ssl_certificate_key": "/etc/ssl/private/example.key",
    "server_name": "example.com"
  }
}

Для более глубокого анализа, например, «performance», можно изменить параметр --analysis:

bashКопировать
graphify-skill --source file --path ./nginx.conf --analysis "performance"

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

См. также Claw-code: автономный музейный экспонат на Rust — пример того, как можно интегрировать Graphify‑Skill в процесс аудита конфигураций.

Часто задаваемые вопросы

Как Graphify-Labs/graphify обеспечивает локальный парсинг AST и почему это важно для безопасности?

Graphify парсит исходный код на машине клиента, строя AST без передачи данных в облако. Все операции происходят локально, поэтому нет риска утечки проприетарного кода. Это особенно критично при работе с конфиденциальными проектами, где даже временная отправка кода может нарушить политику доступа. Локальный парсинг также гарантирует предсказуемое поведение и воспроизводимость результата.

Какие типы данных поддерживает Graphify-Labs/graphify помимо кода?

Помимо кода, инструмент принимает схемы баз данных, конфигурационные файлы и PDF‑документы. Схемы позволяют добавить в граф описание таблиц, отношений и индексов. Конфиги интерпретируются как набор параметров и связей, а PDF‑файлы преобразуются в текст, из которого выделяются структуры и ссылки. Такой мультимодальный подход делает Graphify универсальным для построения контекста.

Как использовать Graphify в составе локальных ИИ‑агентов, например, в Cursor или Claude CLI?

Для интеграции с Cursor, Claude CLI или другими локальными агентами достаточно вызвать /graphify-skill с указанием пути к файлам или директории. Инструмент вернёт JSON‑описание графа, которое можно загрузить в память агента через API или файл‑кэш. Это позволяет агенту работать с полным контекстом проекта без необходимости передавать весь код в удалённый сервис. В результате агент получает точные ссылки на функции, переменные и зависимости, что повышает точность его выводов.

Какие ограничения имеет локальный AST‑парсинг и как их можно обойти?

Ограничения включают поддержку только тех языков, для которых реализован парсер, и отсутствие автоматического анализа динамического кода, выполняемого в рантайме. Кроме того, парсер может не учитывать сложные метапрограммные шаблоны, такие как рефлексия в Python или макросы в Rust. Для расширения возможностей можно добавить пользовательские плагины‑парсеры или предварительно запустить статический анализатор, который подготовит дополнительные метаданные для Graphify. Всё это сохраняет локальный характер работы и не требует отправки данных наружу.