22 операции: полный справочник фасада
Каждая операция — назначение, ключевые флаги, что в результате и какие пределы объявляет. Конверт ответа и правила чтения.
Как устроен контракт #
Все операции доступны тремя путями: Python-фасад (op_), CLI (ragraf query …) и MCP-инструменты (ragraf_, 23 штуки — list_capabilities дополнительно раскрывает режим). Каждая отвечает конвертом единого формата:
{
"op": "impact", "index_rev": "rev-0016", "capability": "full",
"drift": {"files": 0, "symbols": 0, "entries": 0},
"provenance": "index",
"limits": ["статический анализ; динамика не покрыта"],
"stale_warnings": [],
"result": [ ... ]
}Правила чтения: limits объявлены всегда (их отсутствие — баг, а не удача); stale_warnings заполняются автоматически по журналу расхождений; capability: degraded означает, что CPG-слой недоступен и slice откажет; коды выхода CLI: 0 успех · 1 аргументы/корпус · 2 внутренняя ошибка · 3 «операция невозможна в этом состоянии».
Операции по группам #
Навигация и символы #
| Операция | Что делает | Ключевые флаги | Пределы |
|---|---|---|---|
symbol | определение символа по имени/FQN: file:line, подпись, kind, провенанс | --name, --kind, --scope, --limit, --live, --reason | неоднозначное имя → несколько фактов; динамические объявления не покрываются |
references | где символ упомянут (в т.ч. строковые упоминания FQN) | --name, --exclude-definition, --limit | строковые упоминания ≠ вызовы — разделяются в выдаче |
callers | входящие вызовы символа | --name, --mode hard|all, --limit | hard — только stated-рёбра; динамика (call_user_func) — в all отдельным блоком |
callees | исходящие вызовы | аналогично | аналогично |
members | состав класса/модуля | --name | — |
impact | транзитивное влияние изменения ( BFS по графу) | --name, --depth, --mode, --limit | динамические пути помечены derived; глубина ограничена конфигом |
slice | межпроцедурный срез (Joern CPG) | --name, --direction, --depth | только capability=full; при degraded — отказ с причиной |
live_read | прямое чтение файла мимо индекса | --path, --from, --to | всегда доступен; результат provenance: live |
live_grep | regex-поиск по дереву мимо индекса | --pattern, --glob | всегда доступен |
search | гибридный поиск (FTS5 BM25 + векторы) | --query, --top, --with-text, --mode | семантика ограничена моделью 384d; --with-text отдаёт фрагменты за один вызов |
code | выдача текста чанков по идентификаторам | --entry-ids | — |
Схема данных (БД) #
| Операция | Что делает | Пределы |
|---|---|---|
schema | таблицы/колонки/FK из миграций и information_schema | у фактов схемы нет path:line — проверяемость M6 их не считает (честные 24,4% вместо 100%) |
table_usage | где таблица читается/пишется в коде | связка по SQL-литералам; динамически собранный SQL не покрывается |
write_check | сверка плана записи (таблица+колонки) со схемой до выполнения | возвращает nearest-предложения при опечатке колонки; не проверяет бизнес-правила |
column_usage | использования колонки | как table_usage |
data_flow (schema) | поток данных таблица→код | статический, по SQL-литералам |
Маршруты и политики #
| Операция | Что делает | Пределы |
|---|---|---|
routes | веб-маршруты (path→handler) из конфигурации/аннотаций | покрытие зависит от парсера маршрутов проекта |
policy_trace | трассировка прав доступа: маршрут→middleware→проверка роли | статическая трассировка; рантайм-конфигурация ACL не исполняется |
Состояние и метрики #
| Операция | Что делает |
|---|---|
status | сводка ревизии: файлы, узлы, рёбра, чанки, capability, тайминги стадий |
health | самодиагностика: файлы хранилищ, схемы, деградации |
index_status | детальное состояние индексации и журнала |
reindex | явная пересборка ревизии с архивацией журнала |
drift_report | отчёт «что изменилось в знаниях» по журналу/архиву |
usage_stats | телеметрия обращений: по операциям, фактам, спанам, токенам |
selftest | отчёт по 9 обязательным + 2 опциональным компонентам (всегда exit 0 — это отчёт, не гейт) |
Точный состав 22 операций фасада может незначительно расходиться с табличной группировкой выше — источник истины:src/ragraf/facade.pyиdocs/operations.mdв репозитории. Здесь grouping учебный: навигация (11), схема (5), маршруты/политики (2), состояние (7) ≈ 22+3 служебных CLI-операции (status/health/selftestживут и как команды верхнего уровня).
Анатомия результата: provenance в деле #
Пример реального вывода callers --mode all для динамического PHP:
stated (доказано графом):
z_agr_audit_log ← Workflow.php:210 (edge_uid 3f2a…)
z_agr_audit_log ← DocRoute.php:88 (edge_uid 91bc…)
derived (эвристика, отдельно):
z_agr_audit_log ← call_user_func в hooks.php:44 confidence 0.60
→ требует проверки live_readДва блока никогда не смешиваются. Вывод для агента: на stated можно опираться; derived — список мест, которые надо открыть (live_read) и проверить глазами/моделью.
Что операции НЕ делают #
- Не пишут и не патчат код (RAGRAF отвечает — правит агент).
- Не выполняют SQL и не подключаются к БД (схема — из миграций и read-only information_schema).
- Не ходят в сеть (единственный сетевой трафик продукта — установка зависимостей и одноразовое скачивание модели эмбеддингов).
- Не дают произвольных запросов к графу (принцип P4 — см. проблематику).
Лимиты и безопасность выдачи #
Каждая операция несёт явные --limit (защита от раздувания контекста агента) и глобальные ограничения из конфига корпуса. Ответы не содержат значений секретов: файлы secrets_exclude не индексируются вовсе, а телеметрия хранит хеши аргументов.
Смежное: CLI-справочник → · конфигурация корпуса → · как читать конверт в регламенте агента →