Загрузите историю git репозитория в граф с помощью расширения git-to-graph от Relate, предоставьте его в режиме только для чтения и посмотрите, что агент по написанию кода найдет с его помощью, чего он не может найти в дереве исходного кода.
В популярной базе открытого исходного кода файл security/api_key.py был изменен в 28 коммитах. В 18 из них также изменился oauth2.py. http.py изменился в 17, а open_id_connect_url.py — в 16. Ни один из этих четырех модулей не импортирует другой, поэтому в api_key.py нет ничего очевидного, что указывало бы на остальные три файла.
История ясно объясняет причину. Каждый раз, когда кто-то добавлял поведение в одну схему безопасности, он добавлял его во все остальные: auto_error в #134, описание в #1757, код состояния 401 в #13786, поддержка WebSocket в #10147.
Мы спросили трех агентов по написанию кода, что еще им нужно изменить перед добавлением аргумента конструктора в APIKeyHeader. Имея для чтения только дерево исходного кода, ни один из них не назвал эти три модуля. Когда история репозитория была загружена в граф, все трое справились с задачей.
В этой статье показано, как построить такой граф с помощью расширения Relate’s git-to-graph, что у него спросить и что изменилось, когда Codex, OpenCode и Pi смогли выполнять к нему запросы.
Relate: база данных, созданная для агентов
Relate — это база данных графов с открытым исходным кодом, созданная для прямого использования агентами ИИ. Она встраиваемая: один бинарный файл, не нужно развертывать сервер или регистрироваться, а вся база данных представляет собой один файл .rl на вашем компьютере, к которому ваш агент обращается на языке Cypher.
«Агент-ориентированность» означает, что все необходимое агенту поставляется вместе с ним. Команда relate skill install дает агенту по написанию кода навык, который документирует CLI, его диалект Cypher и включает каталог готовых запросов. Команда relate serve — mcp предоставляет любую базу данных в качестве инструментов MCP, а флаг --read-only заставляет ее отклонять любые попытки записи.
Расширения Relate можно использовать для загрузки внешних данных в граф. В этой статье используются два из них: для истории репозитория и fs-to-graph для его рабочего дерева.
Построение графа: две команды, около 20 секунд
git-to-graph считывает историю коммитов рабочей копии. fs-to-graph считывает ее рабочее дерево. Оба записывают данные в одно и то же хранилище Relate, поэтому один граф содержит информацию о том, что представляет собой код и как он появился.
Для FastAPI (8 102 коммита с декабря 2018 по ноябрь 2026 года) импорт истории занял 4,6 секунды, а импорт файлов — 14 секунд. Хранилище представляет собой один файл размером 30 МБ; клон, из которого оно было получено, весит 101 МБ. Повторный запуск импорта истории безопасен: он выполняет слияние, поэтому второй запуск оставил те же 48 322 ребра совместных изменений.
Две детали важны в дальнейшем:
- Пути включают каталог, который вы импортировали. Мы запускали импортеры из родительского каталога, поэтому файл пакета — fastapi/fastapi/routing.py.
- Увеличьте лимит содержимого для больших файлов. fs-to-graph по умолчанию хранит текст файлов размером до 64 КБ. Файл routing.py в FastAPI имеет размер 260 КБ, а applications.py — 185 КБ, поэтому по умолчанию два самых редактируемых файла остались без текста. Флаг --max-content-bytes 400000, указанный выше, охватывает каждый файл Python в репозитории.
Три вопроса перед редактированием
Связь CO_CHANGED объединяет два файла, которые появились в одном коммите, а ее счетчик — это количество коммитов, в которых встречался этот шаблон. Эта связь отвечает на первый вопрос, который агент должен задать перед редактированием файла.
Что еще мне нужно будет затронуть?
Для fastapi/fastapi/security/api_key.py:
Для fastapi/fastapi/routing.py, файла на 6 552 строки со 193 коммитами, в верхней части списка находятся applications.py (58), dependencies/utils.py (47) и openapi/utils.py (39). Треть всех коммитов в routing.py также изменила applications.py.
Делал ли кто-то подобные изменения раньше?
Счетчики показывают, какие файлы изменяются вместе. Более ранние коммиты показывают, как выглядело изменение такого рода. Этот запрос находит коммиты в файле, тема которых совпадает с термином, и перечисляет, что еще было затронуто в каждом из них:
С параметром $path, установленным на api_key.py, и $term на security, четыре из пяти строк затронули те же самые три исходных файла:
- 1884325c (2026-10-18) — Добавить поддержку WebSocket в зависимости безопасности (#10147). Исходные файлы: open_id_connect_url.py, oauth2.py, http.py. Тесты: 3.
- 51ad909f (2025-11-24) — Использовать код состояния 401 в классах безопасности при учетных данных… Исходные файлы: open_id_connect_url.py, oauth2.py, http.py. Тесты: 23.
- 3b2e8919 (2021-07-29) — Добавить параметр описания во все классы схем безопасности… Исходные файлы: open_id_connect_url.py, oauth2.py, http.py. Тесты: 11.
- fad3a9e1 (2019-04-03) — Добавить auto_error в утилиты безопасности (#134). Исходные файлы: open_id_connect_url.py, oauth2.py, http.py. Тесты: 10.
Это шаблон для изменения: коммит с описанием — это более ранний аргумент конструктора, и он показывает, какие файлы и сколько тестов были с ним связаны.
Кто должен это проверить?
Для routing.py и applications.py:
Столбец last_touch оправдывает свое место. Если ранжировать только по коммитам, вторым рецензентом окажется человек, чье последнее изменение в этих файлах было в 2019 году. Два человека ниже в списке касались их в течение последнего года или около того.
Чего не показывает чтение кода
Модули безопасности — это не разовое явление. Поскольку fs-to-graph помещает текст каждого файла в тот же узел, что и его историю, один запрос может найти файлы, которые изменяются вместе, хотя текст ни одного из них не упоминает другой:
Внутри пакета fastapi/ 126 пар файлов изменялись вместе пять и более раз. Для 42 из них (треть) этот запрос не находит ссылок ни в одном из направлений. Проверка основана на совпадении имен в тексте файла, а не на графе импорта, поэтому считайте число приблизительным. Тем не менее, это список, который невозможно получить, просто отслеживая импорты.
Передайте это агенту
Relate может предоставлять хранилище через MCP в режиме только для чтения:
Сервер предоставляет два инструмента: read_cypher и get_schema. Отправка MATCH (n:Person) DETACH DELETE n в read_cypher возвращается как ошибка инструмента и оставляет хранилище без изменений:
Для Codex добавьте сервер в ~/.codex/config.toml:
Для OpenCode добавьте его в ~/.config/opencode/opencode.json:
Pi получил доступ к тому же хранилищу через командную строку relate, также в режиме только для чтения:
Для всех троих команда relate skill install --agent <name> добавляет навык, который включает каталог готовых запросов к истории, чтобы агент не начинал с чистого листа.
Вот один из вызовов read_cypher, который Codex сделал для задачи по безопасности. В подсказке ему было сказано использовать граф, но не было предоставлено никаких запросов. Движок ответил за 0,3 мс:
Сравнение
Мы дали Codex 0.167.1, OpenCode 2.2.7 и Pi 1.5.2 две одинаковые задачи, все на одной модели (gpt-6.1-sol, среднее рассуждение). Каждый агент работал в отдельном контейнере.
- Задачи: Добавить необязательный аргумент конструктора в APIKeyHeader и добавить именованный аргумент в APIRouter.add_api_route. В обоих случаях агенту было сказано ничего не редактировать, а сначала проинструктировать нас: какие еще файлы изменятся, какие тесты запустить и кто должен проверить.
- Только код. У агента есть копия FastAPI с удаленным каталогом .git, а также его обычные инструменты поиска и чтения.
- С графом. Та же копия, также без .git, плюс граф. Его единственный источник истории — Relate.
Вот что содержал каждый брифинг за 12 сессий:
Три вещи выделяются:
Кода достаточно для тестов, а для файлов импорт делает их видимыми. Каждый агент в обеих группах назвал одни и те же основные тесты; агенты, работающие только с кодом, пришли к этому, прочитав файлы тестов. Каждый агент нашел applications.py, который импортирует routing.
Кода недостаточно для файлов, на которые нет ссылок. Ни один брифинг, основанный только на коде, не упоминает ни один из трех связанных модулей безопасности. Агенты, использующие граф, сделали это и обосновали свой выбор. OpenCode написал, что эти три модуля «изменялись вместе с api_key.py 17, 18 и 16 раз соответственно» и их следует проверять на согласованность API, а не «автоматически редактировать». Codex добавил: «Оба предыдущих добавления описания и auto_error затронули все четыре модуля».
Код не может сказать, кто работал над файлом. Агенты, работающие только с кодом, нашли сопровождающего проекта в docs/en/docs/management.md и остановились на этом, о чем они и сообщили. Codex: «Я не могу определить специалиста по маршрутизации или недавнего участника разработки этих методов только по этому чек-ауту». Pi: «Без истории или явного владения компонентами я не могу определить недавних сопровождающих этого конкретного кода». С графом все трое назвали людей по тому, что они изменили, например, автора предыдущего аргумента описания.
Как это работает
git-to-graph делает один вызов git log для всей истории, строит план в памяти и записывает его в шесть пакетных фаз MERGE: люди, коммиты, файлы, затем три типа отношений. Он создает индексы диапазонов перед записью и полнотекстовый индекс по темам коммитов после.
Само расширение небольшое, потому что оно не владеет базой данных. Это дочерний процесс, который общается с хостом Relate через MCP; хост владеет хранилищем, пакетной обработкой транзакций и лимитами. Если вам нужен импортер для источника, который Relate не охватывает, relate extension init <name> создает шаблон на shell, Python, TypeScript или Rust.
Два флага управляют окном. --since считывает все после даты, а --until закрывает диапазон, поэтому более старая эпоха импортируется одинаково каждый раз:
Попробуйте на своей кодовой базе
Все, что описано в этом посте, запускается в вашем собственном репозитории за четыре шага: установка relate, загрузка истории, запуск сервера только для чтения и информирование вашего агента об этом.
Установите бинарный файл и два расширения:
Запустите импортеры из каталога над вашим чек-аутом, чтобы пути в графе начинались с имени репозитория. Первый считывает историю коммитов, а второй добавляет рабочее дерево, оба в один файл:
Затем передайте граф вашему агенту. Установите навык, который содержит каталог запросов истории, и зарегистрируйте хранилище как MCP-сервер только для чтения.
Любой агент, который поддерживает MCP через stdio, может запустить эту команду:
Теперь задайте вопрос из начала этого поста о файле, который вы хорошо знаете:
- Что еще меняется при изменении этого файла?
- Делал ли кто-нибудь подобные изменения раньше?
- Кто работал над этим?
Ресурсы
Relate
- Relate by Neo4j домашняя страница
- Установить relate: CLI для macOS, Linux или Windows
- Исходный код на GitHub
Расширения в этом посте
- Импорт истории git с помощью git-to-graph: граф, который он строит, его флаги и ограничения
- Импорт дерева каталогов с помощью fs-to-graph: текст файла, ограничение содержимого и полнотекстовый индекс
- Установка и запуск расширения
- Написание расширения: создание шаблона импортера для источника, который Relate не охватывает
Передача графа агенту
- Подключите вашего агента к relate: краткое руководство по агенту
- Подключение через MCP: блоки конфигурации для Claude Code, Cursor, Codex, OpenCode и других
- Установка навыка агента
- Обеспечение безопасности агента: открытия только для чтения, лимиты и резервные копии
- Агент-ориентированный дизайн: почему CLI и сервер ведут себя именно так
Дальнейшие шаги
- Ответы на вопросы по кодовой базе, недоступные для текстового поиска: рецепт из кулинарной книги, основанный на том же графе
- Кулинарная книга Relate
- Model Context Protocol
Используемые здесь репозитории и инструменты












