İçeriğe geç
V1 dokümanları
Yerel dizinler

Referanslar

Referanslar, OpenCode’a mevcut projenin dışındaki dizinlere erişim sağlar. Çalışırken belgeleri, paylaşılan kütüphaneleri, örnekleri veya başka bir depoyu kullanılabilir hale getirmek için bunları kullanın.

Referanslar, opencode.json veya opencode.jsonc içinde bir takma adla yapılandırılır.

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions",
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details",
    },
  },
}

Yerel bir dizine referans vermek için path kullanın.

opencode.jsonc
{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}

Yollar şunlar olabilir:

  • Referansı tanımlayan yapılandırma dosyasına göre göreli
  • /home/user/docs gibi mutlak
  • ~/docs gibi ana dizininize göre göreli

Kısa bir dize gösterimi de kullanabilirsiniz:

opencode.jsonc
{
  "references": {
    "docs": "../docs",
  },
}

Bir Git deposuna referans vermek için repository kullanın. OpenCode depoyu yerel depo önbelleğinde oluşturur ve checkout edilen kaynak kodu bir referans dizini olarak kullanılabilir hale getirir.

opencode.jsonc
{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

repository; Git URL’lerini, host/path referanslarını ve GitHub owner/repo kısa gösterimini kabul eder. İsteğe bağlı branch alanı bir dal veya ref seçer. branch belirtilmezse OpenCode deponun varsayılan dalını kullanır.

Dal, açıklama veya başka seçeneklere ihtiyacınız yoksa kısa dize gösterimini kullanabilirsiniz:

opencode.jsonc
{
  "references": {
    "effect": "Effect-TS/effect",
  },
}

Bir agent’ın bir referansı ne zaman kullanması gerektiğini açıklamak için description ekleyin.

opencode.jsonc
{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when implementing UI components or design tokens",
    },
  },
}

OpenCode, açıklaması olan referansları agent bağlamına ekler. Açıklamalar, benzer içeriğe sahip referansları ayırt edecek kadar kısa ve belirgin olmalıdır. Açıklaması olmayan referanslar otomatik tamamlama ve doğrudan kullanım yoluyla erişilebilir kalır, ancak agent’lara bildirilmez.


Bir referansı TUI’deki @ otomatik tamamlamasından çıkarmak için hidden değerini true olarak ayarlayın.

opencode.jsonc
{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}

hidden yalnızca otomatik tamamlamayı etkiler. Açıklaması olan gizli bir referans agent bağlamına dahil edilmeye devam eder.


Yapılandırılmış referanslar TUI’deki @ otomatik tamamlamasında görünür. Referansın kök dizinini eklemek için @alias, içindeki dosyaları aramak için @alias/ yazın.

Compare this implementation with @sdk/src/client.ts

Agent’lar ayrıca açıklaması olan yapılandırılmış referansların çözümlenmiş yollarını ve açıklamalarını sistem bağlamlarında alır. Böylece bir referans ilgili olduğunda, siz elle eklemeden onu inceleyebilirler.

OpenCode, referans dizinlerine harici dizin izin sınırı üzerinden otomatik olarak izin verir. Normal araç izinleri yine geçerlidir; örneğin dosya düzenleyemeyen bir agent, bir dizin referans olarak yapılandırıldı diye düzenleme erişimi kazanmaz.


AlanYerelGitAçıklama
pathEvetHayırYerel referans dizini
repositoryHayırEvetGit URL’si, host/path veya GitHub owner/repo değeri
branchHayırEvetİsteğe bağlı Git dalı veya ref
descriptionEvetEvetReferansın ne zaman kullanılacağını açıklayan yönlendirme
hiddenEvetEvetReferansı TUI @ otomatik tamamlamasından gizler

Referans takma adları boş olamaz ve /, boşluk, ters tırnak veya virgül içeremez.