opencode-codegraph — поддерживаемый адаптер CodeGraph для OpenCode. Он добавляет графовый контекст
к промптам, управляемые команды, инструменты явных контекстных сессий, ревью и подсказки после
команд. Порядок запуска описан в Быстром старте, а здесь —
поведение и границы адаптера.
Установка и регистрация
Для прямого подключения добавьте opencode-codegraph в массив plugin файла
opencode.json в корне проекта. OpenCode загружает перечисленные там npm-плагины при
запуске. См. руководство OpenCode по плагинам.
Сохраните остальные плагины и параметры конфигурации:
{
"plugin": ["opencode-codegraph"]
}
Чтобы подготовить локальную копию исходников CodeGraph, запустите скрипт из корня репозитория.
Для этого нужны Python-зависимости CodeGraph, Node.js/npm, установленный OpenCode и
зарегистрированный проект с CPG. Замените PROJECT именем проекта. Скрипт готовит
конфигурацию MCP, LSP, плагина и API:
python scripts/run_opencode_codegraph.py --project 'PROJECT'
Модель скрипта запуска по умолчанию — openai/gpt-5.4. Выберите модель, доступную вашей
учётной записи OpenCode, и задайте её через --model или CODEGRAPH_OPENCODE_MODEL.
Каталог MCP зависит от профиля сервера. Получите доступные инструменты через настроенное соединение.
Если скрипт не находит проект, проверьте его регистрацию и значение --project.
Порядок проверки описан в Быстром старте.
Параметры окружения
Адаптер читает:
| Переменная | Назначение |
|---|---|
CODEGRAPH_API_URL |
Корень API CodeGraph; по умолчанию http://localhost:8000 |
CODEGRAPH_PROJECT |
Явная область проекта для API-вызовов плагина |
Плагин подключается к API CodeGraph и настроенному MCP-серверу. Контекст и дальнейшие рекомендации зависят от графа и данных рабочего процесса, доступных для выбранного проекта.
Контракт хуков OpenCode
Поддерживаемый исходник регистрирует хуки:
| Хук | Текущая роль |
|---|---|
experimental.chat.system.transform |
Добавить контекст проекта и рабочего процесса в системную инструкцию |
command.execute.before |
Подготовить контекст управляемой команды с префиксом / |
chat.message |
Дополнить запрос контекстом файла, правки или рабочего процесса |
tool.execute.after |
Реагировать на тесты, Git-команды и коммиты |
Плагин получает события OpenCode и сохраняет контекст дочерних сессий. Хуки добавляют к запросу контекст проекта и подсказывают дальнейшие действия. После распознанного Git-коммита плагин запрашивает инкрементальное обновление CPG и показывает его асинхронный статус.
Команды и инструменты
Поддерживаются файлы из текущего .opencode/commands: /audit, /continue, /explain, /next,
/onboard, /review, /status и /update. Каждый файл задаёт инструкции для своей команды.
Адаптер предоставляет инструменты работы с графом и ревью, а также инструменты контекстных сессий.
Полный каталог MCP поступает от настроенного сервера. Массивы и объекты MCP передавайте как
нативные значения.
По руководству MCP инициализируйте соединение,
получите tools/list и проверьте правила вызова выбранного профиля.
Команды дают единый вход к типовым задачам CodeGraph:
| Команда | Результат |
|---|---|
/audit |
Ограниченный аудит: готовность, выводы, доказательства и следующий шаг |
/continue |
Следующий разрешённый шаг текущей явной задачи и сессии |
/explain |
Объяснение кода по исходникам и данным проекта |
/next |
Лучшее следующее действие по процессу, без его запуска |
/onboard |
Границы проекта, языки, признаки архитектуры и готовность |
/review |
Выводы по заданному изменению со ссылками на использованные данные |
/status |
Состояние проекта, контекстной сессии и готовности CPG |
/update |
Повторная проверка готовности и доступного действия обновления |
Контекст и продолжение
Плагин показывает режим контекста: полный, ожидание синхронизации или данные только графа. По этому статусу видно, какие данные доступны для запроса. Открывайте сессию, предоставляйте доступ для чтения и передавайте владение через инструменты контекстных сессий CodeGraph.
Лёгкое состояние в .opencode/state связывает локальный сеанс OpenCode с CodeGraph. История
диалога хранится в авторитетной сессии сервера. Новые мутации выполняются в активной сессии;
закрытые и архивные сессии сохраняются для чтения.
Поведение после коммита
После распознанного Git-коммита tool.execute.after может запросить локальное инкрементальное
обновление через авторизованный сервис CodeGraph и показать состояние ожидания или завершения.
Приём запроса асинхронный: завершение CPG, контекстной синхронизации и ревью отслеживайте по
соответствующим статусам.
Проверка и откат
Для удалённого MCP OpenCode использует собственную конфигурацию и OAuth-адаптер.
Вход через opencode mcp auth codegraph, выход, привязка проекта
и восстановление описаны в руководстве по удалённой авторизации MCP.
python scripts/run_opencode_codegraph.py --project 'PROJECT' --run "/status"
При OpenCode 1.2.27 или невозможности определить его версию скрипт использует
неинтерактивный режим без регистрации плагина и LSP. В этом режиме проверяйте ответ
/status; хуки плагина проверяйте в интерактивной сессии.
Проверьте в ответе /status проект, режим контекста и свежесть CPG. Затем выполните
/explain для одного файла или функции и сопоставьте ссылки в ответе с исходниками.
Чтобы отключить плагин, удалите только opencode-codegraph из массива plugin
в рабочем opencode.json и заново откройте OpenCode. Остальные записи массива сохраните.
Для возврата к предыдущей одобренной версии установите её и сохраните регистрацию плагина.
Связанные руководства
- Быстрый старт OpenCode — подготовка проекта и первый запрос.
- Руководство MCP — подключение и проверка каталога инструментов.
- Удалённая авторизация MCP — вход, выбор проекта и восстановление подключения.