OpenCode plugins подключают исполняемые расширения, которые реагируют на события и меняют поведение OpenCode. Команда может разместить файл плагина в проекте либо указать пакет в конфигурации, затем проверить его действия в отдельном репозитории. Такой код получает контекст рабочего процесса, поэтому источник и доступ к данным изучают до использования с рабочими файлами.
Реакция на события
По документации OpenCode, плагин представляет собой модуль JavaScript или TypeScript, который возвращает обработчики событий. Локальные файлы проекта загружаются из каталога .opencode/plugins/ при запуске.
Начните с действия, которое хочется изменить. Допустим, при завершении сессии разработчик хочет получить локальное уведомление, а при запуске инструмента — записать техническое событие в журнал. Плагин может подписаться на событие session.idle или tool.execute.before и выполнить свой код. В документации также перечислены события изменения файла, запроса разрешения и состояния сессии. Выбирайте конкретный триггер и проверяемый результат; абстрактное пожелание «улучшить работу агента» ведёт к лишним обработчикам.
Это именно исполняемое расширение поведения. Навык с инструкциями описывает процедуру для агента, MCP-сервер предоставляет отдельные инструменты и данные, а плагин запускает свои обработчики в ответ на события OpenCode. Плагин также способен добавить собственный инструмент, если это предусмотрено кодом. Связку с внешними инструментами отдельно разбирает статья про MCP в OpenCode. Здесь центр внимания — момент запуска кода и последствия его работы.
Перед выбором готового расширения запишите контракт: какое событие оно слушает, какие поля получает, что меняет и где виден результат. Например, журналирование события должно оставлять понятную запись без содержимого секретных файлов. Для обработчика перед вызовом инструмента обозначьте допустимые изменения аргументов. Если плагин изменяет команду или окружение запуска, ревьюеру нужна возможность увидеть исходный вызов и преобразованный вариант. Такой контракт пригодится для теста и последующего обновления.
Источник и установка
Официальная инструкция описывает два пути загрузки: локальный файл JavaScript или TypeScript в каталоге проекта .opencode/plugins/ либо пакет npm, указанный в поле plugin конфигурации opencode.json. Существует и глобальный каталог плагинов пользователя. Выбирайте область проекта, когда код расширения относится к одному репозиторию и проходит ревью. Глобальную установку учитывайте отдельно: она влияет на работу в других проектах пользователя.
| Источник | Что сверить до запуска | Как зафиксировать решение |
|---|---|---|
| Файл проекта | Код обработчиков и изменения в каталоге .opencode/plugins/ | Ссылка на ревью файла и владелец |
| Пакет npm | Публикация, версия, зависимости и содержимое поставки | Запись о пакете и согласованной версии |
| Глобальная настройка | Перечень затронутых проектов и доступ к данным | Отдельное согласование области применения |
Для npm-пакетов OpenCode использует Bun при запуске и кэширует зависимости. Это значит, что строка в конфигурации ведёт к загрузке исполняемого кода, а список зависимостей входит в предмет проверки. Сверьте название пакета с источником публикации, изучите его релиз и зафиксируйте выбранную версию. Если происхождение кода остаётся туманным, оставьте пакет вне рабочего контура до разбора. Для локального файла проверьте импорты и то, какие дополнительные пакеты нужны ему для работы.
OpenCode загружает плагины из глобальной и проектной конфигурации, а также из соответствующих каталогов файлов. Одно и то же поведение может возникнуть из нескольких источников. Запишите активные места загрузки и свяжите действие с конкретным модулем. Локальный и npm-плагин со сходными названиями способны загрузиться отдельно. Проверка лишь проектного файла поэтому даёт неполную картину, если у разработчика есть глобальные расширения.
Данные и полномочия
Разберите вход плагина как код с доступом к рабочему контексту. Документация показывает объект контекста с каталогом проекта, рабочим деревом, клиентом OpenCode и интерфейсом командной оболочки Bun. Через обработчики плагин может видеть события сессии, вмешиваться в вызовы инструментов или добавлять собственный инструмент. Изучайте фактические обращения к файлам, сети и командам, а также данные, которые уходят во внешнюю систему. Границы доступа определяют код расширения и настройки среды.
Составьте карту полномочий: источник кода, события, читаемые пути, изменяемые файлы, выполняемые команды, адреса отправки и журнал результата. Особое внимание уделите обработчикам tool.execute.before, shell.env и собственным инструментам. Они способны изменить параметры действия или окружение команд. Читайте исходный код и зависимости в согласованной версии, затем проверяйте наблюдаемое поведение. Секреты в отчёт ревью заносить нельзя; достаточно указать способ хранения и категорию доступа.
У OpenCode есть настройки разрешений для действий агента: правила allow, ask и deny описаны в официальном разделе Permissions. Проверьте действующие правила проекта и пользователя до испытания плагина. При этом ограничения кода расширения проверяют отдельно от правил агента. Для внешнего сервиса доступ и подтверждения проверяет сервер. Тестируйте реальные ограничения в среде исполнения и на стороне сервиса, а текст инструкции используйте только как дополнительное описание процесса.
После карты прав понятно, какую задачу безопасно поручить пробному репозиторию. Запишите ожидаемые события и допустимые изменения до установки, чтобы наблюдение имело критерий. Если первой проверке нужны секреты, подготовьте тестовые данные. Аудит прав ИИ-агентов подробнее рассмотрен в статье о доступах и секретах.
Какое событие OpenCode требует проверки доступа в вашем проекте?
Проба в репозитории
Предложите пробу на отдельном репозитории с искусственными файлами. Подготовьте минимальную задачу, в которой событие действительно возникает, и заранее снимите состояние файлов. Например, для обработчика завершения сессии ожидайте запись в локальном журнале, а для обработчика вызова инструмента — видимое решение о допустимом действии. В пробном проекте отключите ненужные глобальные расширения либо учтите их отдельно в журнале, иначе источник результата будет трудно установить.
- Сохраните исходный код плагина или зафиксируйте пакет и выбранную версию. Запишите ожидаемый обработчик и допустимое действие.
- Разместите файл в проектном каталоге плагинов либо добавьте пакет в конфигурацию пробного проекта. Запустите OpenCode для загрузки расширения.
- Вызовите выбранное событие на тестовых данных. Сопоставьте журнал, изменения файлов и вызовы команд с заранее описанным контрактом.
- Проверьте пограничный сценарий: отмену действия, ошибку обработчика или запрос к закрытому файлу. Смотрите на фактический результат среды и сервиса.
- Уберите расширение из проекта, повторите ту же задачу и убедитесь, что связанное с ним поведение исчезло. Отдельно проверьте внешние подключения.
Результат оценивают по следу события и выполненным действиям. Сохраните дифф проекта, запись журнала и перечень выполненных команд. Если плагин отправляет данные наружу, в тесте используйте контролируемый адрес и согласованную схему наблюдения. Внешнюю интеграцию подтверждает её владелец. Для обработчика, который изменяет аргументы инструмента, сравните входные и итоговые параметры без публикации чувствительных значений.
Отдельно проверьте повторный запуск: расширение должно выдавать ожидаемый результат при том же событии, а ошибки должны оставлять читаемый след для разработчика. Если несколько плагинов слушают один триггер, учитывайте порядок их загрузки и последовательность обработчиков, описанную в документации. Разбор сценариев проверки и отката ИИ-агентов поможет оформить такую пробу: тестирование ИИ-агентов.
Удаление и ревизия
После пробы решите, нужен ли плагин в рабочем репозитории. Для допуска сохраните источник, выбранную версию, владельца, события, права и результат теста. Код локального файла меняется вместе с проектом, поэтому ревью изменений удобно включить в обычный процесс проверки. Для npm-пакета пересматривайте поставку и зависимости при обновлении. Проверяйте, какие обработчики добавились и изменился ли список внешних адресов или исполняемых команд.
Удаление зависит от способа загрузки. Для проектного файла удалите согласованным изменением сам файл из каталога плагинов; для пакета уберите запись из конфигурации. После следующего запуска повторите контрольную задачу и проверьте отсутствие прежнего поведения. Если тот же модуль есть в глобальной конфигурации, он способен продолжить работу, поэтому сверяйте все источники загрузки. Отдельно закрывайте созданные плагином внешние доступы по правилам соответствующего сервиса.
Храните реестр расширений команды рядом с решениями о доступе: какой проект использует модуль, какое событие его запускает, кто отвечает за код и где лежит проверенная версия. При неожиданном изменении файлов начинайте с журнала событий и списка активных плагинов. Такой разбор позволяет найти источник действия до правки промпта. Для команды с несколькими рабочими контурами полезен разбор ИИ-инструментов, расширений и доступов на собственных процессах.
Хорошее правило приёмки формулируется через наблюдаемый результат: событие вызывает только согласованное действие, данные остаются в разрешённом контуре, а удаление прекращает работу обработчика. Если результат нельзя проверить на отдельном репозитории, рабочее подключение откладывают до уточнения контракта. Плагин остаётся программой внутри рабочего процесса; управлять им следует как кодом с источником, владельцем и понятным способом отключения.