Плагины

Пишите собственные плагины для расширения OpenCode.

Плагины позволяют расширять OpenCode, подключаясь к различным событиям и настраивая поведение. Вы можете создавать плагины для добавления новых функций, интеграции с внешними сервисами или изменения стандартного поведения OpenCode.

Ознакомьтесь с плагинами, созданными сообществом, в качестве примеров.

Использование плагина

Есть два способа загрузки плагинов.

Из локальных файлов

Поместите файлы JavaScript или TypeScript в директорию плагинов.

.opencode/plugins/ - Плагины уровня проекта
~/.config/opencode/plugins/ - Глобальные плагины

Файлы в этих директориях автоматически загружаются при запуске.

Из npm

Укажите npm-пакеты в файле конфигурации.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}

Поддерживаются как обычные, так и scoped npm-пакеты.

Просмотрите доступные плагины в экосистеме.

Как устанавливаются плагины

npm-плагины автоматически устанавливаются с помощью Bun при запуске. Пакеты и их зависимости кэшируются в ~/.cache/opencode/node_modules/.

Локальные плагины загружаются напрямую из директории плагинов. Для использования внешних пакетов необходимо создать package.json в директории конфигурации (см. Зависимости) или опубликовать плагин в npm и добавить его в конфигурацию.

Порядок загрузки

Плагины загружаются из всех источников, и все хуки выполняются последовательно. Порядок загрузки:

Глобальная конфигурация (~/.config/opencode/opencode.json)
Конфигурация проекта (opencode.json)
Глобальная директория плагинов (~/.config/opencode/plugins/)
Директория плагинов проекта (.opencode/plugins/)

Дублирующиеся npm-пакеты с одинаковым именем и версией загружаются только один раз. Однако локальный плагин и npm-плагин с похожими именами загружаются отдельно.

Создание плагина

Плагин - это модуль JavaScript/TypeScript, который экспортирует одну или несколько функций плагина. Каждая функция получает объект контекста и возвращает объект хуков.

Зависимости

Локальные плагины и пользовательские инструменты могут использовать внешние npm-пакеты. Добавьте package.json с необходимыми зависимостями в директорию конфигурации.

.opencode/package.json

{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

OpenCode выполняет bun install при запуске для их установки. После этого ваши плагины и инструменты могут их импортировать.

.opencode/plugins/my-plugin.ts

import { escape } from "shescape"
 
export const MyPlugin = async (ctx) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash") {
        output.args.command = escape(output.args.command)
      }
    },
  }
}

Базовая структура

.opencode/plugins/example.js

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")
 
  return {
    // Реализации хуков здесь
  }
}

Функция плагина получает:

project: Информация о текущем проекте.
directory: Текущая рабочая директория.
worktree: Путь к git worktree.
client: SDK-клиент opencode для взаимодействия с ИИ.
$: Shell API (opens in a new tab) Bun для выполнения команд.

Поддержка TypeScript

Для плагинов на TypeScript вы можете импортировать типы из пакета плагинов:

my-plugin.ts

import type { Plugin } from "@opencode-ai/plugin"
 
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Типобезопасные реализации хуков
  }
}

События

Плагины могут подписываться на события, как показано в разделе Примеры ниже. Вот список доступных событий.

События команд

command.executed

События файлов

file.edited
file.watcher.updated

События установки

installation.updated

События LSP

lsp.client.diagnostics
lsp.updated

События сообщений

message.part.removed
message.part.updated
message.removed
message.updated

События разрешений

permission.asked
permission.replied

События сервера

server.connected

События сессии

session.created
session.compacted
session.deleted
session.diff
session.error
session.idle
session.status
session.updated

События задач

todo.updated

События Shell

shell.env

События инструментов

tool.execute.after
tool.execute.before

События TUI

tui.prompt.append
tui.command.execute
tui.toast.show

Примеры

Вот несколько примеров плагинов, которые вы можете использовать для расширения opencode.

Отправка уведомлений

Отправляйте уведомления при возникновении определенных событий:

.opencode/plugins/notification.js

export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Отправить уведомление при завершении сессии
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
      }
    },
  }
}

Мы используем osascript для запуска AppleScript на macOS. Здесь мы используем его для отправки уведомлений.

Примечание: Если вы используете десктопное приложение OpenCode, оно может автоматически отправлять системные уведомления, когда ответ готов или когда в сессии произошла ошибка.

Защита .env

Предотвратите чтение файлов .env opencode:

.opencode/plugins/env-protection.js

export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    },
  }
}

Внедрение переменных окружения

Внедряйте переменные окружения во все выполнения shell (инструменты ИИ и пользовательские терминалы):

.opencode/plugins/inject-env.js

export const InjectEnvPlugin = async () => {
  return {
    "shell.env": async (input, output) => {
      output.env.MY_API_KEY = "secret"
      output.env.PROJECT_ROOT = input.cwd
    },
  }
}

Пользовательские инструменты

Плагины также могут добавлять пользовательские инструменты в opencode:

.opencode/plugins/custom-tools.ts

import { type Plugin, tool } from "@opencode-ai/plugin"
 
export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "This is a custom tool",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, context) {
          const { directory, worktree } = context
          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
        },
      }),
    },
  }
}

Хелпер tool создает пользовательский инструмент, который opencode может вызывать. Он принимает функцию схемы Zod и возвращает определение инструмента с:

description: Что делает инструмент
args: Схема Zod для аргументов инструмента
execute: Функция, которая выполняется при вызове инструмента

Ваши пользовательские инструменты будут доступны в opencode наряду со встроенными инструментами.

Логирование

Используйте client.app.log() вместо console.log для структурированного логирования:

.opencode/plugins/my-plugin.ts

export const MyPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "my-plugin",
      level: "info",
      message: "Plugin initialized",
      extra: { foo: "bar" },
    },
  })
}

Уровни: debug, info, warn, error. Подробности см. в документации SDK (opens in a new tab).

Хуки компактификации

Настройте контекст, включаемый при компактификации сессии:

.opencode/plugins/compaction.ts

import type { Plugin } from "@opencode-ai/plugin"
 
export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Внедрить дополнительный контекст в промпт компактификации
      output.context.push(`
## Custom Context
 
Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on
`)
    },
  }
}

Хук experimental.session.compacting срабатывает перед тем, как LLM генерирует сводку продолжения. Используйте его для внедрения доменно-специфичного контекста, который стандартный промпт компактификации может пропустить.

Вы также можете полностью заменить промпт компактификации, установив output.prompt:

.opencode/plugins/custom-compaction.ts

import type { Plugin } from "@opencode-ai/plugin"
 
export const CustomCompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Заменить весь промпт компактификации
      output.prompt = `
You are generating a continuation prompt for a multi-agent swarm session.
 
Summarize:
1. The current task and its status
2. Which files are being modified and by whom
3. Any blockers or dependencies between agents
4. The next steps to complete the work
 
Format as a structured prompt that a new agent can use to resume work.
`
    },
  }
}

Когда установлен output.prompt, он полностью заменяет стандартный промпт компактификации. Массив output.context в этом случае игнорируется.

Сервер Экосистема