Building plugins

Yetenek ekleme (katkıda bulunanlar için kılavuz)

OpenClaw; gömmeler, görüntü oluşturma, video oluşturma veya gelecekte tedarikçi destekli başka bir özellik alanı gibi yeni bir paylaşılan etki alanına ihtiyaç duyduğunda bunu kullanın.

Kural:

plugin = sahiplik sınırı
yetenek = paylaşılan çekirdek sözleşmesi

Bir tedarikçiyi doğrudan bir kanala veya araca bağlamayın. Önce yeteneği tanımlayın.

Ne zaman yetenek oluşturulmalı?

Yalnızca aşağıdakilerin tümü doğru olduğunda yeni bir yetenek oluşturun:

Birden fazla tedarikçinin bunu uygulayabilmesi makul olmalıdır.
Kanallar, araçlar veya özellik pluginleri, tedarikçiyi önemsemeden bunu tüketebilmelidir.
Çekirdeğin geri dönüş, politika, yapılandırma veya teslim davranışının sahipliğini üstlenmesi gerekir.

Çalışma yalnızca tedarikçiye özgüyse ve henüz paylaşılan bir sözleşme yoksa önce sözleşmeyi tanımlayın.

Standart sıra

Türü belirlenmiş çekirdek sözleşmesini tanımlayın.
Bu sözleşme için plugin kaydını ekleyin.
Paylaşılan bir çalışma zamanı yardımcısı ekleyin.
Kanıt olarak gerçek bir tedarikçi plugini bağlayın.
Özellik/kanal tüketicilerini çalışma zamanı yardımcısına taşıyın.
Sözleşme testleri ekleyin.
Operatöre yönelik yapılandırmayı ve sahiplik modelini belgelendirin.

Ne nereye yerleştirilir?

Katman	Sorumluluk
Çekirdek	İstek/yanıt türleri; sağlayıcı kayıt defteri ve çözümleme; geri dönüş davranışı; iç içe nesne, joker karakter, dizi öğesi ve bileşim düğümlerinde yayılan `title`/`description` dokümantasyon meta verilerine sahip yapılandırma şeması; çalışma zamanı yardımcısı yüzeyi.
Tedarikçi plugini	Tedarikçi API çağrıları, tedarikçi kimlik doğrulama işlemleri, tedarikçiye özgü istek normalleştirmesi ve yetenek uygulamasının kaydı.
Özellik/kanal plugini	`api.runtime.` veya eşleşen `plugin-sdk/-runtime` yardımcısını çağırır. Bir tedarikçi uygulamasını hiçbir zaman doğrudan çağırmaz.

Sağlayıcı ve yürütme düzeneği bağlantı noktaları

Davranış genel ajan döngüsü yerine model sağlayıcısı sözleşmesine ait olduğunda sağlayıcı kancalarını kullanın. Aktarım seçiminden sonraki sağlayıcıya özgü istek parametreleri, kimlik doğrulama profili tercihi, istem katmanları ve model/profil yük devretmesinden sonraki izleme geri dönüşü yönlendirmesi buna örnektir.

Davranış, bir turu yürüten çalışma zamanına ait olduğunda ajan yürütme düzeneği kancalarını kullanın. Yürütme düzenekleri; görünür çıktı olmadan boş çıktı, görünür çıktı olmadan akıl yürütme veya nihai yanıt içermeyen yapılandırılmış plan gibi açık protokol sonuçlarını sınıflandırabilir; böylece dış model geri dönüş politikası yeniden deneme kararını verebilir.

Her iki bağlantı noktasını da dar kapsamlı tutun:

Yeniden deneme/geri dönüş politikasının sahipliği çekirdeğe aittir.
Sağlayıcı pluginleri, sağlayıcıya özgü istek/kimlik doğrulama/yönlendirme ipuçlarının sahipliğini üstlenir.
Yürütme düzeneği pluginleri, çalışma zamanına özgü deneme sınıflandırmasının sahipliğini üstlenir.
Üçüncü taraf pluginleri çekirdek durumunu doğrudan değiştirmek yerine ipuçları döndürür.

Dosya denetim listesi

Yeni bir yetenek için şu alanlara dokunmanız beklenir:

src/<capability>/types.ts
src/<capability>/...registry/runtime.ts
src/plugins/types.ts
src/plugins/registry.ts
src/plugins/captured-registration.ts
src/plugins/contracts/registry.ts
src/plugins/runtime/types-core.ts
src/plugins/runtime/index.ts
src/plugin-sdk/<capability>.ts
src/plugin-sdk/<capability>-runtime.ts
Bir veya daha fazla paketlenmiş plugin paketi.
Yapılandırma, dokümantasyon ve testler.

Uygulamalı örnek: görüntü oluşturma

Görüntü oluşturma standart yapıyı izler:

Çekirdek ImageGenerationProvider öğesini tanımlar.
Çekirdek registerImageGenerationProvider(...) öğesini sunar.
Çekirdek api.runtime.imageGeneration.generate(...) ve .listProviders(...) öğelerini sunar.
Tedarikçi pluginleri (comfy, deepinfra, fal, google, litellm, microsoft-foundry, minimax, openai, openrouter, vydra, xai) tedarikçi destekli uygulamaları kaydeder.
Gelecekteki tedarikçiler, kanalları/araçları değiştirmeden aynı sözleşmeyi kaydeder.

Yapılandırma anahtarı, görsel analiz yönlendirmesinden kasıtlı olarak ayrıdır:

agents.defaults.imageModel görüntüleri analiz eder.
agents.defaults.imageGenerationModel görüntüler oluşturur.

Geri dönüş ve politikanın açık kalması için bunları ayrı tutun.

Gömme sağlayıcıları

Yeniden kullanılabilir vektör gömme sağlayıcıları için registerEmbeddingProvider(...) / embeddingProviders sözleşmesini kullanın. Bu sözleşme kasıtlı olarak bellekten daha geniş kapsamlıdır: araçlar, arama, getirme, içe aktarıcılar veya gelecekteki özellik pluginleri, bellek motoruna bağımlı olmadan gömmeleri tüketebilir. Bellek araması da genel embeddingProviders sağlayıcılarını tüketir.

Eski belleğe özgü kayıt API'si ve memoryEmbeddingProviders sözleşmesi kullanımdan kaldırılmıştır. Tüm yeni gömme sağlayıcıları için registerEmbeddingProvider ve embeddingProviders kullanın.

İnceleme denetim listesi

Yeni bir yeteneği yayımlamadan önce şunları doğrulayın:

Hiçbir kanal/araç tedarikçi kodunu doğrudan içe aktarmıyor.
Paylaşılan yol, çalışma zamanı yardımcısıdır.
En az bir sözleşme testi paketlenmiş sahipliği doğruluyor.
Yapılandırma dokümantasyonu yeni model/yapılandırma anahtarını belirtiyor.
Plugin dokümantasyonu sahiplik sınırını açıklıyor.

Bir PR yetenek katmanını atlayıp tedarikçi davranışını bir kanala/araca sabit kodluyorsa geri gönderin ve önce sözleşmeyi tanımlayın.

İlgili

Plugin iç yapısı — yetenek modeli, sahiplik, yükleme işlem hattı, çalışma zamanı yardımcıları.
Plugin geliştirme — ilk plugin öğreticisi.
SDK'ye genel bakış — içe aktarma eşlemesi ve kayıt API'si başvurusu.
Skills oluşturma — tamamlayıcı katkıda bulunan yüzeyi.

Was this useful?