Установка и первый запуск за 10 минут

Windows-установщик и pip-путь, ensure, первая индексация, первый запрос и подключение агента — с реальными числами и типичными граблями.

Требования #

Компонент	Значение
Python	3.13+ (проверено на 3.14); права администратора не нужны
Платформа	Windows + PowerShell 7.6 проверена; Linux/macOS — общий pip-путь (не верифицирован E2E)
Диск	~2,5 ГБ окружение; индекс ~1 МБ на 1–2 файла исходников
Опционально	JDK 21 + Joern (~5–6 ГБ) для CPG-слоя; GPU для ускорения эмбеддингов
Сеть	PyPI при установке; один раз ~240 МБ модель эмбеддингов

Путь A — Windows (проверенный) #

PowerShell

./scripts/install.ps1                 # venv в ~/.ragraf/venv, зависимости, самопроверка
./scripts/install.ps1 -WithTruststore # корпоративный TLS-прокси: pip-сертификаты через truststore
./scripts/install-joern.ps1 -Download # опциональный CPG-слой (SHA-256 проверка архива)

Установщик пишет транскрипт в ~/.ragraf/logs/, проверяет каждый шаг и печатает сводную таблицу; -SummaryJson даёт машиночитаемый итог. Все сетевые операции — с таймаутами и дренажом пайпов (рефакторинг установщика закрыл deadlock при больших выводах — INSTALLER-REFACTOR-NOTES, дефекты D-01…D-17).

Путь B — общий (Linux/macOS/Windows без скриптов) #

Shell

python3.13 -m venv .venv && source .venv/bin/activate
pip install -e .
ragraf --help

Корпус и первая индексация #

Shell

ragraf ensure /path/to/project --json

ensure — команда «приведи в порядок»: находит существующий корпус, для неизвестного каталога создаёт конфиг, при расхождении контрольных сумм переиндексирует. Индекс ложится в <project>/.ragraf/ — добавьте каталог в .gitignore.

Ориентиры времени (323-файловый PHP-корпус, CPU): полная индексация 71 с, из них CPG (Joern) 64 с; без Joern — единицы секунд. Первая индексация с векторами дополнительно скачивает модель (~240 МБ, один раз).

Первые запросы #

Shell

ragraf -p cfg.yaml query search "порог переиндексации" --with-text
ragraf -p cfg.yaml query symbol --name corpus_hash
ragraf -p cfg.yaml query schema --table z_agr_payments
ragraf -p cfg.yaml status

Помните порядок флагов: -p и --json до подкоманды (исключение — ensure --json). Полный список — в CLI-справочнике.

Подключение агента (MCP) #

В конфиг MCP-клиента:

JSON

{
  "mcpServers": {
    "ragraf": {
      "command": "python",
      "args": [
        "/path/to/RAGRAF/tools/ragraf-mcp.py",
        "--project", "/path/to/corpus.yaml",
        "--agent", "my-agent",
        "--agent-kind", "external"
      ]
    }
  }
}

--agent-kind: autoclaw (среда автора — расширенная телеметрия) · external · internal. Сервер отдаёт 23 инструмента ragraf_* по stdio. Пошаговые сценарии для AutoClaw, SagaAI и DeepSeek Harness — в разделе интеграций сайта.

Админ-панель (опционально) #

Shell

ragraf admin        # → http://127.0.0.1:8777 (только loopback)

Токен мутаций печатается в консоль при старте (или RAGRAF_ADMIN_TOKEN). Как устроена панель и что показывает — в статье о панели; интерактивная копия — эмулятор на сайте.

Типичные грабли первых минут #

Симптом	Причина	Лечение
`не распознанный аргумент -p`	флаг после подкоманды	`ragraf -p cfg query …`
selftest «красный», но всё работает	selftest — отчёт, не гейт (всегда exit 0)	читать тело отчёта: joern/java опциональны
`certificate verify failed` при скачивании модели	корпоративный TLS-прокси	`install.ps1 -WithTruststore` или `pip install truststore`
`slice` отвечает кодом 3	нет Joern → capability=degraded	`install-joern.ps1 -Download` или жить без slice
модель не скачивается, интернет есть, но ответы без векторов	`--no-vectors` в истории команд	пересобрать: `ragraf reindex`

Дальше: регламент работы агента →