Przejdź do treści
Dokumentacja V1
Użyj wtyczki

Wtyczki

Wtyczki umożliwiające wyłączenie opencode poprzez podjęcie różnych zdarzeń i zachowanie. Można utworzyć wtyczkę, aby sprawdzić nowe funkcje, integrować się z usługami lub sprawdzaniem zachowania opencode.

Aby znaleźć się z przykładami, przejrzyj wtyczki utworzone przez społeczność.


Istnieją dwa sposoby ładowania wtyczek.


Miejsce plików JavaScript lub TypeScript w katalogu wtyczki.

  • .opencode/plugins/ - Wtyczki na poziomie projektu
  • ~/.config/opencode/plugins/ - Wtyczki globalne

Pliki w tych katalogach są automatycznie ładowane podczas uruchamiania.


szczegółowy pakiet npm w pliku konfiguracyjnym.

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

Obsługiwane są zarówno pakiety zwykłe, jak i pakiety npm o określonym zakresie.

Przeglądaj dostępną wtyczkę w ekosystemie.


wtyczki npm są instalowane automatycznie przy użyciu Bun podczas uruchamiania. Pakiety i ich zależności są buforowane w ~/.cache/opencode/node_modules/.

Wtyczki lokalne są ładowane bezpośrednio z katalogu wtyczek. Aby uzyskać dostęp do zewnętrznych pakietów, musisz zainstalować package.json w swoim katalogu konfiguracyjnym (zobacz Zależności) lub opublikować wtyczkę w npm i dodaj ją do swojej konfiguracji.


Wtyczki są ładowane ze wszystkich źródeł, a wszystkie hooki napisane po kolei. Kolejność ładowania do:

  1. Konfiguracja globalna (~/.config/opencode/opencode.json)
  2. Konfiguracja projektu (opencode.json)
  3. Globalny katalog wtyczek (~/.config/opencode/plugins/)
  4. Katalog wtyczek projektu (.opencode/plugins/)

Zduplikowane pakiety npm o tej samej nazwie i wersji są ładowane raz. Równie ważny jest dostęp lokalny i zewnętrzny npm o dodatkowych nazwach, które są zewnętrzne.


Wtyczka do moduł JavaScript/TypeScript, który eksportuje jeden lub więcej wtyczek funkcje. dostępna funkcja korzystania z obiektu kontekstu i głównego obiektu hooks.


Lokalne narzędzie i narzędzie, które można wykorzystać z zewnętrznych pakietów npm. Dodaj package.json do swojego katalogu konfiguracyjnego z zależnościami.

.opencode/package.json
{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

opencode uruchomienie bun install przy uruchomieniu, aby je uruchomić. Twoje dodatkowe funkcje będą dostępne po zaimportowaniu.

.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 {
    // Hook implementations go here
  }
}

Funkcja dostępu do:

  • project: Aktualne informacje o projekcie.
  • directory: Bieżący katalog roboczy.
  • worktree: Ścieżka eksploatacyjna Git.
  • client: Klient SDK z opencode do sztucznej inteligencji.
  • $: API obudowy Buna do wykonywania oprogramowania.

W przypadku wtyczek TypeScript możesz importować typy z pakietu wtyczek:

my-plugin.ts
import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

Wtyczki mogą subskrybować zdarzenia, jak zastosować poniżej sekcji Przykłady. Oto lista różnych działań.

Wydarzenia dowodzenia

  • command.executed

Plik Wydarzenia

  • file.edited
  • file.watcher.updated

Wydarzenia instalacyjne

  • installation.updated

Wydarzenia LSP

  • lsp.client.diagnostics
  • lsp.updated

Wydarzenia w wiadomościach

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

Wydarzenia związane z uprawnieniami

  • permission.asked
  • permission.replied

Wydarzenia serwerowe

  • server.connected

Wydarzenia sesyjne

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

Wydarzenia shell

  • shell.env

Wydarzenia narzędziowe

  • tool.execute.after
  • tool.execute.before

Wydarzenia TUI

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

Oto kilka dostępnych wtyczek, które można udostępnić do opencode.


Wysyłaj powiadomienia, gdy wystąpią określone zdarzenia:

.opencode/plugins/notification.js
export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Send notification on session completion
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
      }
    },
  }
}

Używamy osascript do uruchamiania AppleScript na macOS. Tutaj możesz przejść do wysyłania pozostałości.


Zablokuj opencode czytanie plików .env:

.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")
      }
    },
  }
}

Wstrzyknij zmienne konsekwencje dla wszystkich wykonań (narzędzia AI i terminale użytkownika):

.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
    },
  }
}

Wtyczki mogą również dodawać niestandardowe narzędzia do 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})`
        },
      }),
    },
  }
}

Pomocnik tool tworzy narzędzie użytkowe, które może wywołać kod opencode. Pobierane schematu Zoda i narzędzie wyszukiwania za pomocą:

  • description: Co robi do narzędzia
  • args: Schemat Zoda dla narzędzi argumentów
  • execute: Funkcja uruchamiania po wywołaniu narzędzia

Twoje narzędzie będzie dostępne dla otwartego kodu wraz z narzędziami użytkowymi.


użyj client.app.log() zamiast console.log do rejestracji strukturalnego:

.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" },
    },
  })
}

Poziomy: debug, info, warn, error. Aby uzyskać szczegółowe informacje, zobacz dokumentację pakietu SDK.


Dostosuj kontekst dołączony podczas kompaktowania sesji:

.opencode/plugins/compaction.ts
import type { Plugin } from "@opencode-ai/plugin"

export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Inject additional context into the compaction prompt
      output.context.push(`
## Custom Context

Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on
`)
    },
  }
}

Hak experimental.session.compacting jest uruchamiany, zanim LLM wygeneruje podsumowanie kontynuacji. go, aby wstrzyknąć kontekst kontekstu dla domeny, której nie dostrzeżono przez domyślny monit o zagęszczenie.

Można także umieścić kompletny monit o zagęszczenie, ustawiając 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) => {
      // Replace the entire compaction prompt
      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.
`
    },
  }
}

Gdy urządzenie jest output.prompt, jest całkowicie dostępne na domyślnym monit o zagęszczanie. Tablica output.context jest w tym przypadku poniesiona.