Araç sistemi referansı

file_read

Yetenekler:

• Tam dosya içeriğini veya belirli satır aralıklarını okuma
• Değişikliklerden önce kodu anlamak için temel
• Aralık belirterek büyük dosyaları verimli işleme

Kullanım senaryoları:

• Düzenlemeden önce yapılandırma dosyalarını okuma
• Mevcut uygulama desenlerini anlama
• Kapsamı anlamak için test dosyalarını inceleme

Örnek:

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

Yetenekler:

• Tam dizi eşleştirmesiyle hassas metin değiştirme
• multiple bayrağıyla çoklu değiştirme işlemleri
• Dosya yapısını ve biçimlendirmesini koruma

Kullanım senaryoları:

• Fonksiyon uygulamalarını güncelleme
• Yapılandırma değerlerini değiştirme
• Dosyalar genelinde değişken adlarını yeniden düzenleme

En iyi uygulama: Hedefli değişiklikler için kullanın. Tam yeniden yazımlar için bunun yerine file_write kullanın.

file_write

Yetenekler:

• Sıfırdan yeni dosyalar oluşturma
• Mevcut dosya içeriğini tamamen değiştirme
• Herhangi bir metin tabanlı biçimi işleme

Kullanım senaryoları:

• Yeni bileşenler veya modüller oluşturma
• Yapılandırma dosyaları oluşturma
• Test dosyaları yazma

Uyarı: Mevcut dosyaların üzerine tamamen yazar. Kısmi değişiklikler için file_edit kullanın.

glob

Yetenekler:

• Desenlerle eşleşen dosyaları bulma: **/*.ts, src/**/*.js
• Dizin yoluna göre filtreleme
• Sonuçları daraltmak için hariç tutma desenleri
• Sonuç sayısını kontrol etme

Kullanım senaryoları:

• Bir projedeki tüm bileşenleri bulma
• Test dosyalarını konumlandırma
• Dizinler genelinde yapılandırma dosyalarını belirleme

Örnek desenler:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

Yetenekler:

• Regex desenlerini kullanarak dosya içeriğinde arama
• Eşleşmelerden önce/sonra bağlam satırlarını gösterme (-B, -A bayrakları)
• Büyük/küçük harf duyarsız arama
• Glob desenleri kullanarak dosya türüne göre filtreleme

Kullanım senaryoları:

• Fonksiyon tanımlarını bulma
• API uç noktası uygulamalarını konumlandırma
• Belirli hata mesajlarını arama
• Güvenlik desenlerini belirleme

Örnek:

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

Yetenekler:

• Desen eşleşmeleri içeren dosyaları listeleme
• Yalnızca dosya konumlarına ihtiyacınız olduğunda grep_content'ten daha hızlı
• Regex deseni desteği
• Dosya türleri için glob filtreleme

Kullanım senaryoları:

• Hangi dosyaların yeniden düzenlenmesi gerektiğini belirleme
• Belirli modülleri içe aktaran dosyaları bulma
• Kullanımdan kaldırılmış desenlere sahip dosyaları konumlandırma

En iyi uygulama: İlgili dosyaları belirlemek için önce grep_file, ardından detaylı inceleme için file_read kullanın.

list_dir

Yetenekler:

• Dizin hiyerarşisini gösterme
• max_depth parametresiyle derinliği kontrol etme
• Çıktıyı filtrelemek için hariç tutma desenleri

Kullanım senaryoları:

• Proje yapısını anlama
• Dizin organizasyonunu doğrulama
• Belirli alt dizinleri bulma

bash

Yetenekler:

• Shell komutlarını çalıştırma
• Maksimum zaman aşımı: 120 saniye (2 dakika, kesin sınır)
• Bağımlılıklar için komutları && ile zincirleme
• Netlik için açıklayıcı özetler sağlama

Kullanım senaryoları:

• Testleri çalıştırma
• Projeleri derleme
• Bağımlılıkları yükleme
• Git işlemleri
• Veritabanı taşımaları

Örnek:

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

Güvenlik: Komutlar kullanıcı izinleriyle çalışır. Komutları Manual Accept Mode'da inceleyin.

spawn_subagent

Yetenekler:

• İzole bağlamlara sahip özel alt aracıları başlatma
• Türler: explorer, verifier, code-reviewer
• Ana bağlamı kirletmeden karmaşık görevleri devretme
• Verimlilik için paralel alt aracı çalıştırma

Kullanım senaryoları:

• explorer: Büyük kod tabanlarında desen arama
• verifier: Uygulama mantığını doğrulama
• code-reviewer: Güvenlik ve kalite değerlendirmesi

En iyi uygulama: Ana konuşma bağlamını korumak için keşif amaçlı araştırmayı Explorer alt aracına devredin.

todo_update

Yetenekler:

• Görev listeleri oluşturma ve yönetme
• Görev durumunu güncelleme (pending, in_progress, completed)
• Karmaşık uygulamalar genelinde ilerlemeyi izleme

Kullanım senaryoları:

• Çok adımlı özellikleri parçalara ayırma
• Yeniden düzenleme ilerlemesini izleme
• Taşıma görevlerini yönetme

web_search

Yetenekler:

• İnternet arama motorlarını sorgulama
• Sonuç sayısını kontrol etme
• Güncelliğe göre filtreleme (son günler)

Kullanım senaryoları:

• Tanımadığınız API'ler için belge bulma
• Hata mesajlarını araştırma
• Güncel en iyi uygulamaları kontrol etme

web_fetch

Yetenekler:

• Web sayfası içeriğini alma
• İçeriği belirli sorgularla analiz etme
• Yapılandırılmış bilgi çıkarma

Kullanım senaryoları:

• Belge sayfalarını okuma
• API belgelerini analiz etme
• Öğreticilerden örnekler çıkarma

Veri biçimleri

Derleme ve paket dosyaları

file_read verimliliği

En iyi uygulamalar:

• Bağlam aşırı yüklenmesini önlemek için 500 satırı aşan dosyalarda satır aralıkları kullanın
• Yalnızca görev için gereken ilgili bölümleri okuyun
• Büyük dosyalar için ilgili satır numaralarını belirlemek üzere önce grep_content kullanın

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

file_edit hassasiyeti

En iyi uygulamalar:

• Başarısız düzenlemeleri önlemek için tam dizi eşleşmeleri sağlayın
• Benzer birden çok değişiklik için multiple=true bayrağını kullanın
• Düzenlemeden önce dosya yollarını doğrulayın

file_write güvenliği

En iyi uygulamalar:

• Kazara üzerine yazmayı önlemek için yolları iki kez kontrol edin
• Yalnızca yeni dosyalar veya tam yeniden yazımlar için kullanın
• Değişiklikler için güvenlik açısından file_edit tercih edin

glob deseni özgüllüğü

En iyi uygulamalar:

• Kapsamı daraltmak için belirli desenler kullanın: **/* yerine src/**/*.ts
• Hariç tutma desenleriyle dizinleri hariç tutun: !**/node_modules/**
• Aşırı çıktıyı önlemek için sonuçları sınırlayın

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

grep stratejisi

Önerilen iş akışı:

1. İlgili dosyaları belirlemek için grep_file kullanın
2. Belirli dosyaları file_read ile okuyun
3. Çevreleyen bağlama ihtiyacınız olduğunda grep_content kullanın

Performans ipuçları:

• Regex desenleri düz dizilerden daha uzun sürebilir
• Büyük/küçük harf duyarsız aramalar daha yavaştır
• Bağlam satırlarını (-A, -B) gereken kadarla sınırlayın

bash en iyi uygulamaları

Güvenli komut çalıştırma:

• Komut açıklamaları için net özetler sağlayın
• Uzun süren işlemler için uygun zaman aşımları ayarlayın
• Bağımlı komutları && ile zincirleyin
• Yıkıcı komutları dikkatlice inceleyin (rm, drop, truncate)

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

Güvenlik hususları

Kritik güvenlik kuralları:

• Komutlar kullanıcı izinleriyle çalışır
• Güvenilmeyen komutları asla çalıştırmayın
• Paylaşılan kod tabanlarında inceleme için Manual Accept Mode kullanın
• Kimlik bilgilerini veya hassas verileri açığa çıkaran komutlardan kaçının

Alt aracı devretme verimliliği

Alt aracılar ne zaman kullanılır:

• Explorer: Kod tabanı aramaları, mimari soruları (ana bağlamı korur)
• Verifier: Hızlı doğrulama kontrolleri (izole doğrulama)
• Code-reviewer: Güvenlik ve kalite incelemeleri (detaylı analiz)
• General: Karmaşık çok adımlı görevler (paralel çalıştırma)

En iyi uygulama: Ana konuşma bağlamını aktif geliştirme çalışması için korumak amacıyla keşif ve araştırma görevlerini alt aracılara devredin.

Bağlam yönetimi

Stratejik araç kullanımı:

• Dosyaları stratejik olarak okuyun - yalnızca gerekeni
• Arka plan araştırması için alt aracıları kullanın
• Uzun oturumlar sırasında bağlam tüketimini izleyin
• Karmaşık işlemleri todo_update ile adımlara bölün

Verimli iş akışları:

1. Planlama: Kapsamı belirlemek için glob/grep kullanın
2. Okuma: Yalnızca ilgili dosyaları/bölümleri okuyun
3. Çalıştırma: Uygun olduğunda alt aracılara devredin
4. Doğrulama: Verifier alt aracısıyla hızlı kontroller

Dosya boyutu sınırları

Büyük dosya işleme: Çok büyük dosyalar (>10.000 satır) şunları önlemek için bölümler halinde okunmalıdır:

• Bağlam penceresi tükenmesi
• Yavaş yanıt süreleri
• Bellek sorunları

Araç zaman aşımı varsayılanları

Araç sınırları:

• Bash zaman aşımı: Maksimum 120 saniye (2 dakika)
• Dosya işlemleri: Boyut sınırı yok (büyük dosyalar otomatik olarak gruplar halinde okunur)
• Büyük dosya işleme: >256KB dosyalar içeriğin yalnızca ilk 256KB'sini döndürür
• Arama sonuçları: glob veya grep_content sonuçlarında sınır yok
• Eşzamanlı alt aracılar: Paralel çalıştırmada sınır yok

Zaman aşımı yapılandırması:

• Uzun süren işlemler için açık zaman aşımları ayarlayın
• Takılı kalan işlemleri izleyin
• 2 dakikalık zaman aşımını aşan komutlar sonlandırılır

Eşzamanlı işlemler

Paralel çalıştırma: Daha hızlı karmaşık işlemler için birden çok alt aracı paralel olarak çalışabilir. Ana aracı koordinasyonu otomatik olarak yönetir.

Performans avantajları:

• Çok adımlı görevler için toplam çalıştırma süresinin azaltılması
• Verimli kaynak kullanımı
• Otomatik görev orkestrasyonu
• Eşzamanlı alt aracı sayısında sınır yok