Skip to content

Releases: paulmann/RAGRAF

Release list

v0.1.0 — первый публичный выпуск RAGRAF

v0.1.0 — первый публичный выпуск RAGRAF Latest
Latest

Choose a tag to compare

View all tags
@paulmann paulmann released this 12 Oct 07:47
v0.1.0
6a62a07

Первый публичный выпуск RAGRAF — графово-векторной базы знаний о коде для LLM-агентов.

Что это

Агент, работающий над правкой кода, тратит основную часть контекста на поиск места: где определена функция, кто её вызывает, как сделано похожее рядом. RAGRAF заменяет путь «rg плюс чтение файлов целиком» индексом: агент задаёт вопрос фиксированной операцией и получает факт со ссылкой файл:строка.

Замерено на реальном проекте (14 задач навигации): 28 вызовов инструментов без индекса против 14 с индексом, попадание в файл-цель с первого запроса — 92%, проверяемость фактов — 100%, файлов целиком не читается ни одного (вместо 14). Числа вызовов, попадания и проверяемости — измерения из bench/; «реалистично 43» — модельная поправка, записанная в самих артефактах.

Оговорка, которую обычно опускают: выигрыш в 2–3 раза относится к задачам локализации. В цикле «прочитал → изменил → проверил» экономии по числу вызовов почти нет — выигрыш там в другом: правки не ломают индекс, а спорный SQL проверяется до запуска.

Возможности

  • 22 операции над репозиторием без языка запросов к графу: search, symbol, references, callers/callees, impact, slice, code, repo_map, schema, table_usage, routes, policy_trace, class_usage, write_check, live_read, freshness, index_status, drift_report/drift_ack, catalog, calibrate, usage.
  • 23 инструмента MCP (ragraf_*) — подключение к агенту как stdio-сервер; те же операции доступны из CLI.
  • Три хранилища SQLite на корпус в каталоге .ragraf/ внутри индексируемого проекта: граф кода, лексика FTS5 плюс векторы, ревизии с журналом расхождений.
  • 16 языков разбираются деревом (PHP, Python, JavaScript, TypeScript, Java, C#, C, C++, Ruby, Lua, Go, Perl, bash, PowerShell, CSS, HTML); ещё 10 подключаются текстом.
  • Локальные эмбеддинги (ONNX, без torch), гибридный поиск BM25 плюс вектор.
  • Необязательный слой графа свойств кода (Java + Joern): без него продукт работает и честно объявляет capability=degraded, операция slice отказывает с причиной.

Установка

# Windows, PowerShell 7.6+, Python 3.13+
git clone https://github.com/paulmann/RAGRAF.git
cd RAGRAF
pwsh -NoLogo -NoProfile -File scripts/install.ps1

Установщик создаёт окружение вне репозитория, ставит зависимости и проверяет результат по шагам, с итоговой таблицей. Варианты: -Project <каталог> (сразу подготовить корпус), -Index (полная индексация), -NoVectors, -WithTruststore (в сети с TLS-инспекцией), -SummaryJson <путь> (машиночитаемый итог для конвейера).

Первая индексация с векторами скачивает модель, около 240 МБ. Индексация без векторов модель не скачивает, лексический поиск продолжает работать.

Общий путь для других платформ: python -m venv .venv && pip install -e . (на Linux и macOS не проверялся).

Первые шаги

ragraf ensure C:\work\myproject              # найти корпус, досоздать, пересобрать отставший индекс
ragraf -p <конфиг> selftest                 # отчёт по 11 компонентам (всегда код 0 — это не гейт)
ragraf -p <конфиг> query search "что ищем"
ragraf -p <конфиг> query symbol --name corpus_hash
ragraf -p <конфиг> check                    # изменился ли код после индексации

Что внутри выпуска

Документация. Английский README как основной, русские оригиналы сохранены (README.ru.md, docs/ru/). Техническое описание: устройство, требования, критерии приёмки (docs/architecture/), интеграция и слой CPG (docs/implementation/), навык работы с ядром (docs/skills/). Реестр найденных дефектов с доказательствами file:line — docs/DEFECTS.md (43 находки). Дорожная карта со стабильными идентификаторами — ROADMAP.md. Отдельная вики из 15 страниц.

Инфраструктура. CI проверяет гигиену (синтаксис, отсутствие BOM и CRLF), запускает анализатор PowerShell, собирает и разворачивает продукт на Windows и Ubuntu с Python 3.13 и 3.14, прогоняет переносимые наборы тестов на синтетических фикстурах, выполняет сквозной прогон на синтетическом корпусе и собирает пакет. Шаблоны для сообщения о дефекте и о расхождении документации с кодом.

Установщик переработан: одновременное чтение потоков внешнего процесса (устраняет взаимную блокировку каналов), таймауты на каждый шаг с множителем, проверка свободного места, разбор отчёта selftest и результата индексации из JSON вместо локализованного текста, журнал запуска, защищённое удаление окружения. Слой Joern ставится с загрузкой и проверкой контрольной суммы до распаковки.

Исправлено при проверке перед выпуском

Обнаружено запуском, а не чтением:

  • установщик падал до создания окружения: арифметика в позиции аргумента передавалась строкой в параметр целочисленного массива (два места);
  • шаг CI на синтетическом корпусе создавал один файл кода, а корпус требует не менее трёх — прогон завершался отказом и валил задание;
  • тесты падали на Windows с UnicodeEncodeError: отчёты печатаются по-русски, а консоль Windows по умолчанию не UTF-8 (воспроизведено с cp1252);
  • проверка переводов строк валила Windows-задания всегда: она читала рабочее дерево, которое runner конвертирует в CRLF при checkout (замерено — 83 файла).

Проверено перед выпуском

Установка в чистое окружение — 0 ошибок. Сквозной цикл init → index → search → symbol → code на синтетическом проекте. Сборка sdist и wheel, установка wheel и запуск. Все семь заданий CI — зелёные. Проверка конвенций проекта — 14 из 14. Отсутствие BOM и CRLF во всех публикуемых файлах. Аудит на утечки: 0 секретов, служебные и машинные файлы закрыты .gitignore.

Известные ограничения

  • Проверено на Windows с PowerShell 7.6; другие платформы проходят CI, но вручную не проверялись.
  • Реестр дефектов публикуется открыто: в нём есть незакрытые находки, включая токен админ-панели (панель слушает только localhost) — подробности в SECURITY.md.
  • Часть ссылок в документах указывает на инструменты и тесты, которые в публичную поставку не входят; они помечены как не поставляемые.

Требования

Python 3.13 или новее. Права администратора не нужны. Java и Joern — только для полного графа свойств кода.

Лицензия

MIT.

Assets 4
Loading