389 lines
10 KiB
Plaintext
389 lines
10 KiB
Plaintext
---
|
||
title: Eklentiler
|
||
description: OpenCode'u genişletmek için kendi eklentilerinizi yazın.
|
||
---
|
||
|
||
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](/docs/ecosystem#plugins) göz atın.
|
||
|
||
---
|
||
|
||
## Eklenti kullanımı
|
||
|
||
Eklentileri yüklemenin iki yolu vardır.
|
||
|
||
---
|
||
|
||
### Yerel dosyalardan
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
### npm'den
|
||
|
||
Yapılandırma dosyanızda npm paketlerini belirtin.
|
||
|
||
```json title="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](/docs/ecosystem#plugins)'deki mevcut eklentilere göz atın.
|
||
|
||
---
|
||
|
||
### Eklentiler nasıl kurulur?
|
||
|
||
**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](#dependencies)) veya eklentiyi npm ve [yapılandırmanıza eklemeniz](/docs/config#plugins) gerekir.
|
||
|
||
---
|
||
|
||
### Yükleme sırası
|
||
|
||
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 oluşturma
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
### Bağımlılıklar
|
||
|
||
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.
|
||
|
||
```json title=".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.
|
||
|
||
```ts title=".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)
|
||
}
|
||
},
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Temel yapı
|
||
|
||
```js title=".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](https://bun.com/docs/runtime/shell).
|
||
|
||
---
|
||
|
||
### TypeScript desteği
|
||
|
||
TypeScript eklentileri için türleri eklenti paketinden içe aktarabilirsiniz:
|
||
|
||
```ts title="my-plugin.ts" {1}
|
||
import type { Plugin } from "@opencode-ai/plugin"
|
||
|
||
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
|
||
return {
|
||
// Type-safe hook implementations
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Olaylar
|
||
|
||
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`
|
||
|
||
#### Yapılacaklar Olayları
|
||
|
||
- `todo.updated`
|
||
|
||
#### Kabuk Olayları
|
||
|
||
- `shell.env`
|
||
|
||
#### Araç Olayları
|
||
|
||
- `tool.execute.after`
|
||
- `tool.execute.before`
|
||
|
||
#### TUI Olayları
|
||
|
||
- `tui.prompt.append`
|
||
- `tui.command.execute`
|
||
- `tui.toast.show`
|
||
|
||
---
|
||
|
||
## Örnekler
|
||
|
||
OpenCode'u genişletmek için kullanabileceğiniz bazı eklenti örneklerini burada bulabilirsiniz.
|
||
|
||
---
|
||
|
||
### Bildirim Gönderme
|
||
|
||
Belirli olaylar meydana geldiğinde bildirim gönderin:
|
||
|
||
```js title=".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.
|
||
|
||
:::note
|
||
OpenCode masaüstü uygulamasını kullanıyorsanız yanıt hazır olduğunda veya oturum hataları oluştuğunda otomatik olarak sistem bildirimleri gönderebilir.
|
||
:::
|
||
|
||
---
|
||
|
||
### .env Koruması
|
||
|
||
OpenCode'un `.env` dosyalarını okumasını önleyin:
|
||
|
||
```javascript title=".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 enjekte etme
|
||
|
||
Ortam değişkenlerini tüm kabuk yürütmeye (AI araçları ve kullanıcı terminalleri) enjekte edin:
|
||
|
||
```javascript title=".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
|
||
},
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Özel araçlar
|
||
|
||
Eklentiler ayrıca OpenCode'a özel araçlar da ekleyebilir:
|
||
|
||
```ts title=".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.
|
||
|
||
:::note
|
||
Eğer bir eklenti aracı yerleşik bir araçla aynı adı kullanırsa, eklenti aracı öncelik kazanır.
|
||
:::
|
||
|
||
---
|
||
|
||
### Günlüğe kaydetme
|
||
|
||
Yapılandırılmış günlük kaydı için `console.log` yerine `client.app.log()` kullanın:
|
||
|
||
```ts title=".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](https://opencode.ai/docs/sdk) bakın.
|
||
|
||
---
|
||
|
||
### Sıkıştırma kancaları
|
||
|
||
Bir oturum sıkıştırıldığında içerilen bağlamı özelleştirin:
|
||
|
||
```ts title=".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:
|
||
|
||
```ts title=".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.
|