Регламент интеграции RAGRAF с агентами¶

Документ описывает, как агент должен работать с базой знаний: что вызывать, в каком порядке, чего нельзя делать. Тексты ниже готовы к переносу в AGENTS.md проекта и в skill.

1. Подключение¶

1.1 MCP-сервер (основной канал)¶

Конфигурация MCP-клиента:

{
  "mcpServers": {
    "ragraf": {
      "command": "python",
      "args": [
        "C:/AutoClaw/RAGRAF/tools/ragraf-mcp.py",
        "--project",
        "C:/AutoClaw/RAGRAF/config/revoap.yaml"
      ]
    }
  }
}

Сервер объявляет 40 инструментов с префиксом ragraf_ (проверено по коду src/ragraf/mcp_server.py): index_status, context, drift_report, search, search_multi, duplicates, entrypoints, dead_code, symbol, references, callers, callees, impact, slice, code, repo_map, schema, table_usage, routes, live_read, drift_ack, policy_trace, class_usage, write_check, usage, freshness, catalog, use_project, ensure, diff, note, notes, task, task_stats (§3.4: отчёт по задаче — обращения, факты, решения гейта) — и шесть инструментов живых баз данных: db_schema, db_table, db_relations, db_sample, db_drift, db_cross.

Гейт использования индекса (§3.2) отдельным инструментом не выставляется намеренно: он вызывается хуком клиента (PreToolUse), а ручная проверка идёт через CLI — query gate --payload -. Подключение: harness/README.md.

context отвечает на вопрос «о каком проекте мне сейчас отвечают»: имя разработки, корень, ревизия, свежесть и на каком основании корпус определён (аргумент запуска, рабочий каталог процесса, реестр или use_project). Он работает и без выбранного корпуса — в отличие от остальных операций.

Инструмента свободных запросов к графу нет и не будет (ФТ-15): попытка передать MATCH ... RETURN отвергается с кодом -32602.

1.2 CLI (отладка и ручные операции)¶

python tools/ragraf.py --project config/revoap.yaml status
python tools/ragraf.py --project config/revoap.yaml query impact --target "Core\Config::get" --depth 3

1.3 Предварительная индексация¶

python tools/ragraf.py --project config/revoap.yaml index

Первая индексация скачивает модель эмбеддингов (0,22 ГБ, один раз в <домашний каталог>/.ragraf/models). Дальше — только из кэша.

2. Регламент работы агента¶

2.1 Перед началом работы над задачей¶

1. ragraf_index_status   → узнать ревизию, полноту разбора, доступные возможности
2. ragraf_drift_report   → если журнал непуст, учесть расхождения ДО любых выводов

Почему именно так. Между индексом и кодом могут быть расхождения: индекс в пределах ревизии неизменен, а код правился. Если агент начнёт работу, не посмотрев журнал, он может опереться на факт, который уже неверен, — и не заметит этого.

2.2 Ответ на вопрос о коде¶

Вопрос агента	Операция
«где это лежит?»	`ragraf_symbol`, при неуверенности — `ragraf_search`
«как устроен модуль?»	`ragraf_repo_map` (в бюджете токенов; поле `chars_used` — фактический объём, а не оценка по синтетической строке)
«кто это вызывает?»	`ragraf_callers`
«что оно вызывает?»	`ragraf_callees`
«что сломается, если изменить?»	`ragraf_impact` (перед правкой — обязательно)
«где ещё используется?»	`ragraf_references`
«какие данные текут сюда?»	`ragraf_slice` (только при `capability=full`)
«что в таблице и кто её читает?»	`ragraf_schema`, `ragraf_table_usage`
«какие есть маршруты?»	`ragraf_routes`
«покажи код»	`ragraf_code` (только по явному запросу)
«что это за фрагмент?»	`ragraf_search` с `with_text: true` — адрес и текст одним вызовом
«покажи это место подробнее»	`ragraf_code` с `entry_ids` из хита (`node_id`/`chunk_id`)

2.2.1 Текст берётся из индекса, а не с диска¶

Замер 12 октября 2026: search возвращал только адрес хита, поэтому текст приходилось забирать ВТОРЫМ вызовом, а code всегда читал файл с диска — даже когда индекс отвечал ровно то же самое. Изменения:

search --with-text добавляет к каждому хиту поле snippet — начало сырого текста чанка из индекса. Признак text_from_index: true подтверждает, что текст взят из базы; если для части хитов текста нет, это видно в limits с числом таких хитов, а не молчаливой пустой строкой.
code по умолчанию отдаёт текст из индекса, а не с диска. Источник назван в каждом спане полем text_source (index либо disk), а провенанс ответа соответствует фактическому источнику. Прежнее поведение доступно как --source disk; профиль корпуса остаётся тот же: индекс не становится источником «истины», он лишь избавляет от лишнего чтения.
code --entry-ids принимает node_id и/или chunk_id из хитов search — до этого их нельзя было передать никуда. Неопознанные идентификаторы возвращаются списком unresolved, а не отбрасываются.

Цена и честность: таблица chunk_text хранит сырой текст чанков; при ротации ревизий он удаляется вместе с ними. Текст в индексе может отстать от файла — тогда срабатывает changed_since_index, и решение о доверии остаётся за вызывающим.

2.3 Жёсткие правила¶

Читать файлы целиком — последнее средство. Сначала операция индекса; rg и чтение файлов — когда индекс ответил «не найдено» или когда факт помечен stale.
Факт с stale_warnings нельзя использовать как основание для вывода. Сначала ragraf_live_read по этому пути.
Тела функций не приходят в impact, slice, repo_map. Это сделано осознанно: структурный контекст точнее и в разы меньше. Код запрашивается отдельно — и, если он нужен, дешевле одним вызовом: search с with_text: true либо code с entry_ids по адресу хита.
Разделять доказанное и эвристическое. В ответах impact и callers блоки stated и derived разделены. Вывод, опирающийся на derived, должен быть помечен как требующий проверки.
Учитывать capability. При degraded недоступны срезы и потоки данных: операция откажет с причиной. Это ограничение, а не пустой результат.
Читать limits. Каждый ответ перечисляет свои ограничения (например, «динамика не покрыта»). Игнорировать их — значит делать выводы на неполной картине.
Во время доработки индекс не обновляется. Правки регистрируются в журнал, не в индекс.

2.4 Во время доработки¶

После правок:

python tools/ragraf.py --project config/revoap.yaml drift --scan

Это сравнит индекс с рабочим деревом и допишет различия в журнал. Индекс при этом не меняется — это принципиально.

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

2.5 После завершения доработки¶

python tools/ragraf.py --project config/revoap.yaml reindex

Что произойдёт: построится новый снимок индекса, журнал расхождений будет архивирован в drift/archive/<из>_to_<в>.md с тремя обязательными разделами — «что изменилось в корпусе», «что в знаниях перепроверено», «изменённые границы срезов». Предыдущие записи и история ревизий не удаляются.

3. Текст для `AGENTS.md` проекта (готов к вставке)¶

## База знаний о коде (RAGRAF)

Перед работой с кодом используй RAGRAF, а не чтение файлов вслепую.

Порядок:
1. `ragraf_index_status` — состояние индекса.
2. `ragraf_drift_report` — если журнал непуст, сначала учти расхождения.
3. Вопросы о коде — через операции: `ragraf_symbol`, `ragraf_callers`, `ragraf_impact`,
   `ragraf_search`, `ragraf_repo_map`.
4. `rg` и чтение файлов целиком — только если индекс ответил «не найдено» либо факт
   помечен `stale` (тогда сначала `ragraf_live_read`).
5. Перед правкой, затрагивающей публичный метод или таблицу, обязательно
   `ragraf_impact` — чтобы не сломать потребителей.
6. После правок: `ragraf drift --scan` (индекс НЕ обновляется).
7. По завершении доработки: `ragraf reindex`.

Запрещено:
- писать запросы к графу (Cypher/CPGQL) — доступен только фиксированный набор операций;
- опираться на факт с пометкой `stale` без предварительного `ragraf_live_read`;
- трактовать `derived`-связи как доказанные;
- игнорировать `limits` и `capability` в ответах.

4. Описание skill¶

Имя: RAGRAF — база знаний о коде Когда применять: любая задача, требующая понимания существующего кода: найти, где реализовано; выяснить, кто вызывает; оценить последствия правки; добавить функциональность в незнакомый модуль.

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

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

5. Что нужно для реального включения¶

Шаг	Состояние
MCP-сервер написан и проверен тестом	✅ `tests/test_mcp.py` — все проверки пройдены
Конфигурация корпуса	✅ `config/revoap.yaml`
Индекс построен	✅ ревизия `rev-0012`, 392 файла
`AGENTS.md` в проекте-пилоте	⏳ не изменялся: файл в чужом проекте, вставка текста из §3 требует согласия владельца
Регистрация MCP-сервера в клиенте	⏳ требует правки конфигурации клиента пользователем
Замеры пользы (M1, M3, M6)	⏳ нужен набор задач и baseline без индекса