İçeriğe geç
V1 dokümanları
Eklenti kullanımı

Eklentiler

Eklentiler, çeşitli olaylara bağlanarak ve davranışı özelleştirerek OpenCode’u genişletmenize olanak tanır. Yeni özellikler eklemek, harici hizmetlerle entegrasyon sağlamak veya OpenCode’un varsayılan davranışını değiştirmek için eklentiler oluşturabilirsiniz.

Örnekler için topluluk tarafından oluşturulan eklentilere göz atın.


Eklentileri yüklemenin iki yolu vardır.


JavaScript veya TypeScript dosyalarını eklenti dizinine yerleştirin.

  • .opencode/plugins/ - Proje düzeyinde eklentiler
  • ~/.config/opencode/plugins/ - Genel eklentiler

Bu dizinlerdeki dosyalar başlangıçta otomatik olarak yüklenir.


Yapılandırma dosyanızda npm paketlerini belirtin.

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

Hem normal hem de kapsamlı npm paketleri desteklenir.

Ekosistem’deki mevcut eklentilere göz atın.


npm eklentileri başlangıçta Bun kullanılarak otomatik olarak yüklenir. Paketler ve bağımlılıkları ~/.cache/opencode/node_modules/’da önbelleğe alınır.

Yerel eklentiler doğrudan eklenti dizininden yüklenir. Harici paketleri kullanmak için, sisteminizin dizininde bir package.json oluşturmanız (bkz. Bağımlılıklar) veya eklentiyi npm ve yapılandırmanıza eklemeniz gerekir.


Eklentiler tüm kaynaklardan yüklenir ve tüm kancalar sırayla çalışır. Yükleme sırası şöyledir:

  1. Global config (~/.config/opencode/opencode.json)
  2. Project config (opencode.json)
  3. Global eklenti dizini (~/.config/opencode/plugins/)
  4. Proje eklenti dizini (.opencode/plugins/)

Aynı ad ve sürüme sahip yinelenen npm paketleri bir kez yüklenir. Ancak benzer adlara sahip bir yerel eklenti ve bir npm eklentisinin her ikisi de ayrı ayrı yüklenir.


Eklenti, bir veya daha fazla eklenti işlevini dışa aktaran bir JavaScript/TypeScript modülüdür. Her işlev bir bağlam nesnesi alır ve bir kanca nesnesi döndürür.


Yerel eklentiler ve özel araçlar harici npm paketlerini kullanabilir. İhtiyacınız olan bağımlılıkları içeren config dizininize bir package.json ekleyin.

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

OpenCode bunları yüklemek için başlangıçta bun install komutunu çalıştırır. Eklentileriniz ve araçlarınız daha sonra bunları içe aktarabilir.

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

Eklenti işlevi şunları alır:

  • project: Mevcut proje bilgisi.
  • directory: Güncel çalışma dizini.
  • worktree: Git çalışma ağacı yolu.
  • client: Yapay zeka ile etkileşim kurmak için bir OpenCode SDK istemcisi.
  • $: Bun’un komutları yürütmek için kullandığı shell API.

TypeScript eklentileri için türleri eklenti paketinden içe aktarabilirsiniz:

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

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

Eklentiler aşağıdaki Örnekler bölümünde görüldüğü gibi etkinliklere abone olabilirler. Burada mevcut farklı etkinliklerin bir listesi bulunmaktadır.

Komut Olayları

  • command.executed

Dosya Olayları

  • file.edited
  • file.watcher.updated

Kurulum Olayları

  • installation.updated

LSP Olayları

  • lsp.client.diagnostics
  • lsp.updated

Mesaj Olayları

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

İzin Olayları

  • permission.asked
  • permission.replied

Sunucu Olayları

  • server.connected

Oturum Olayları

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

Kabuk Olayları

  • shell.env

Araç Olayları

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

TUI Olayları

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

OpenCode’u genişletmek için kullanabileceğiniz bazı eklenti örneklerini burada bulabilirsiniz.


Belirli olaylar meydana geldiğinde bildirim gönderin:

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

macOS’ta AppleScript’i çalıştırmak için osascript kullanıyoruz. Burada bildirim göndermek için kullanıyoruz.


OpenCode’un .env dosyalarını okumasını önleyin:

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

Ortam değişkenlerini tüm kabuk yürütmeye (AI araçları ve kullanıcı terminalleri) enjekte edin:

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

Eklentiler ayrıca OpenCode’a özel araçlar da ekleyebilir:

.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 yardımcısı, OpenCode’un çağırabileceği özel bir araç oluşturur. Bir Zod şeması işlevini alır ve aşağıdakileri içeren bir araç tanımı döndürür:

  • description: Araç ne yapar?
  • args: Aracın argümanları için Zod şeması
  • execute: Araç çağrıldığında çalışan fonksiyon

Özel araçlarınız, yerleşik araçların yanı sıra OpenCode’a da hazır olacaktır.


Yapılandırılmış günlük kaydı için console.log yerine client.app.log() kullanın:

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

Seviyeler: debug, info, warn, error. Ayrıntılar için SDK belgelerine bakın.


Bir oturum sıkıştırıldığında içerilen bağlamı özelleştirin:

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

experimental.session.compacting kancası, LLM bir devam özeti oluşturmadan önce tetiklenir. Varsayılan sıkıştırma isteminin kaçıracağı etki alanına özgü bağlamı enjekte etmek için bunu kullanın.

Ayrıca output.prompt ayarını yaparak sıkıştırma istemini tamamen değiştirebilirsiniz:

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

output.prompt ayarlandığında, varsayılan sıkıştırma isteminin tamamen yerini alır. Bu durumda output.context dizisi dikkate alınmaz.