Yerleşik ajan araçları

Bunlar, yerleşik ajan çalışma zamanının doğrudan kaydettiği sunucuya bağlı araçlardır — dil sunucusu, yapısal arama, hata ayıklayıcı, kernel’ler, sorular ve worker kontrolü — içeri köprülediği MCP araçlarının ve harness çalışma zamanının genel dosya, arama ve shell araçlarının aksine. MCP kayıt defterinde yer almazlar: harici bir MCP istemcisi onları görmez, çünkü her biri tek bir çalıştırmaya ait canlı bir sunucu tarafı kaynağa bağlıdır — bir dil sunucusu süreci, bir hata ayıklama adaptörü, bir yorumlayıcı.

Buradaki her araç, yalnızca arka kaynağı çalıştırma için bağlanmışsa kaydedilir — bir dil sunucusu ya da hata ayıklama gözetmeni, bir tree-sitter ayrıştırıcısı, bir kernel fabrikası, bir soru portu, bir vibe kadrosu. Bu checkout için bir dil sunucusunun ya da hata ayıklama adaptörünün algılanması ayrı ve daha sonraki bir denetimdir (status / adapters): bu araçlar yüzeyde kalır; böylece ajan tahmin yürütmek yerine neden hiçbir şeyin kullanılamadığını sorabilir.

Onay kademeleri

Her araç bir kademe bildirir ve kademe, hangi yüzeylerin onu gördüğüne karar verir — yalnızca onay istemi gösterip göstermeyeceğine değil. Plan modu ve salt okunur alt ajanlar read ile sınırlandırılır; böylece write ya da exec kademesindeki bir araç, şemalarında tamamen yer almaz.

Kademe	Anlamı	Buradaki araçlar
read	Yan etkisi yok	lsp, ast_grep, ask_user, beş vibe_*
write	Dosyaları değiştirir	lsp_rename, ast_edit, resolve
exec	Bir süreç başlatır veya denetler	debug, eval

---

lsp — dil sunucusu sorguları

Bir çalıştırmada bir dil sunucusu gözetmeni ve bir çalışma dizini olduğunda kaydedilir. Bir sunucunun gerçekten yanıt verip veremeyeceği, çağrı anında bir kesişim olarak algılanır: bir kök belirtecin bulunması ve sunucu ikili dosyasının çözümlenmesi gerekir. Tek başına ikisinden biri, sunucunun başlamaması anlamına gelir — status bunu söyler — sessiz bir tahmin yerine.

Konumlar line ile ve bir symbol alt dizesiyle adreslenir, hiçbir zaman sütunla değil. Bir sütun istenen model tahmin yürütür ve yanlış bir tahmin, aynı satırdaki farklı bir sembole çözümlenir — doğru görünen ama başka bir şeyle ilgili bir yanıt. Bir gezinme eyleminde symbol alanını atlamak bir hatadır, ilk sütun tahmini değil.

Eylem	Argümanlar	Döndürdüğü
diagnostics	file (veya "*")	Hatalar ve uyarılar; "*" bunun yerine proje denetleyicisini çalıştırır
definition	file, line, symbol	Sembolün bildirildiği yer
type_definition	file, line, symbol	Türünün bildirildiği yer
implementation	file, line, symbol	Somut uygulamalar
references	file, line, symbol	Her kullanım, 50 ile sınırlı
hover	file, line, symbol	İmza ve belge yorumu
symbols	query veya file	query ile çalışma alanı araması (100 ile sınırlı); file ile belge sembolleri (200 ile sınırlı)
code_actions	file, line, symbol	Sunucunun sunduğu hızlı düzeltmeler
status	—	Hangi sunucuların çalıştığı ve hangi kökler için
reload	—	Bu kök için sunucuyu yeniden başlatır

Yazma sırasında tanılama iletileri

Asıl kazanç araç değildir. write, edit ve apply_patch sarmalanır: yazma işleminden sonra dosya dil sunucusu üzerinden eşitlenip kaydedilir ve araç sonucuna yalnızca yeni ortaya çıkan tanılama iletileri katılır. Ajan derlemeyi bozduğunu, bozduğu anda öğrenir; bunu sormayı hatırlamasına gerek kalmaz.

Daha önce bildirilmiş tanılama iletileri, çalıştırma başına bir defter tarafından bastırılır; bu defter önem derecesi, kod ve ileti üzerinden anahtarlanır — konum bilinçli olarak dışarıda bırakılır, böylece yalnızca dört satır aşağı kaymış bir tanılama ileti yeni olarak yeniden bildirilmez.

lsp_rename — proje çapında yeniden adlandırma

Ayrı bir write kademesi aracı, tam olarak tek bir nedenden ötürü: görünürlüğe kademe karar verir. Yeniden adlandırmayı lsp içine katmak, ya salt okunur bir keşif ajanına depoyu yeniden yazma yeteneği verirdi ya da her hover çağrısını bir onay isteminin arkasına koyardı.

Argüman	Anlamı
file	Sembolün bulunduğu yer
line	1 tabanlı satır
symbol	Onu o satırda tanımlayan alt dize
new_name	Ona ne ad verileceği

---

ast_grep — yapısal arama

Kodu metne göre değil şekle göre bulur. $NAME herhangi bir düğümle eşleşir, $$$NAME bir kardeş dizisiyle eşleşir ve $_ hiçbir şeye bağlanmayan bir joker karakterdir.

Onu, fazladan adımları olan bir regex’ten ziyade gerçek bir eşleştirici yapan özellik şudur: bir desende tekrarlanan bir meta değişkenin aynı metni yakalaması gerekir.

ast_grep(pattern: "if ($X != null) $X.dispose()", language: "dart")

test ettiği şeyi dispose eden bir koruma koşuluyla eşleşir, başka bir şeyi dispose edenle ise eşleşmez.

Argüman	Anlamı
pattern	Meta değişkenler içeren bir kod parçası
path	Aranacak dosya veya dizin; varsayılanı tüm çalışma alanıdır
language	Hazır gelen bir gramer kimliği (dart, python, rust, c, …). path bir dosyayı adlandırdığında çıkarılır
max_results	Varsayılan 50

Desen, dosyayla aynı gramerle ayrıştırılır

Böylece dispose(x), çağrıyı nasıl boşluklandırılmış, sarmalanmış ya da yorumlanmış olursa olsun eşleştirir — ve bir dize sabitinin ya da bir yorumun içindeki aynı karakterlerle hiçbir zaman eşleşmez.

Bir parça çıplak değil, bir iskele içinde ayrıştırılır

Dart’ın üst düzeyinde ayrıştırıldığında dispose(x) geçerli bir işlev imzasıdır. Desen derleyicisi bir bağlam merdiveni dener (deyim, ifade, sınıf üyesi, bildirim) ve parçayı kabul eden ilkini kullanır. Hiçbir bağlamın kabul etmediği bir desen, aranıp sessizce bulunamaz yerine ayrıştırılamaz olarak bildirilir.

ast_edit — yapısal yeniden yazma, sahnelenmiş

Aynı eşleştirme, artı meta değişkenlerin yerine geri konulduğu bir rewrite şablonu. Hiçbir şey yazılmaz. Değişiklik sahnelenir ve sonuç bir edit_id adı verir.

ast_edit(pattern: "dispose($X)", rewrite: "$X.dispose()", language: "dart")
→ (proposed) 12 replacements in 4 files … call resolve with edit_id "edit_1"

Argüman	Anlamı
pattern	Neyin eşleştirileceği
rewrite	$NAME yerine konularak oraya ne yazılacağı
path	Kapsam; varsayılanı tüm çalışma alanıdır
language	Dil kimliği

resolve — sahnelenmiş bir değişikliği işleme alma ya da atma

Argüman	Anlamı
edit_id	(proposed) sonucundan
action	accept ya da discard

Her dosya, sahneleme anında yakalanan içerikle karşılaştırılır ve herhangi bir uyuşmazlık tüm değişikliği reddettirir. Kısmen uygulanmış bir yapısal yeniden yazma, ne eski ne yeni şeklin altında derlenen bir ağaç bırakır.

---

debug — bir hata ayıklayıcıyı yürütme

Bir çalıştırmada bir hata ayıklama oturumu gözetmeni, bir çalışma dizini ve bir konuşma kimliği olduğunda kaydedilir. Bir adaptörün gerçekten başlatılıp başlatılamayacağı, dil sunucusundakiyle aynı kesişim kuralıyla, çağrı anında algılanır (kök belirteci ve ikili dosya). exec kademesi; paralel çalışmaya uygun değil (bir oturum, çağrılar boyunca durumdur; dolayısıyla stack çağrısını geçen bir continue, çoktan yer değiştirmiş bir çerçeveyi okur).

Konuşma başına bir oturum ve katı bir TTL (30 dakika). İkinci bir launch, ilkini sessizce değiştirmek yerine reddedilir.

İşlem	Argümanlar	Notlar
adapters	—	Burada hangi adaptörler kullanılabilir ve hangileri neden değil
status	—	Bir oturumun çalışıp çalışmadığı ve nerede durduğu
breakpoints	file, lines[]	Boş lines, dosyayı temizler. Başlatmadan önce ayarlanabilir
launch	program, args[]	Programı, kesme noktalarınızda durmuş halde başlatır
attach	port	Zaten çalışan bir hata ayıklama hedefine bağlanır
continue	thread_id?	Bir sonraki durma noktasına kadar çalıştırır
pause	thread_id?	Olduğu yerde durdurur
step_over / step_in / step_out	thread_id?	Bir adım ilerletir
threads	—	İş parçacığı kimlikleri ve adları
stack	thread_id?	Çerçeveler, 30 ile sınırlı
scopes	frame_id	Bir çerçevedeki kapsamlar, her biri bir reference ile
variables	reference	Alt öğeler 50, değerler 400 karakter ile sınırlı
evaluate	expression, frame_id?	Çerçevenin kendi kapsamında değerlendirilir
output	—	Hata ayıklama hedefinin stdout/stderr çıktısı, sınırlandırılmış
terminate	—	Oturumu bitirir ve adaptörü sonlandırır

Adaptörler

Kimlik	Komut	Kök belirteçleri
dart	dart debug_adapter	pubspec.yaml
debugpy	python3 -m debugpy.adapter	pyproject.toml, setup.py, requirements.txt
lldb	lldb-dap	Cargo.toml, CMakeLists.txt
delve	dlv dap	go.mod

debugpy, $PATH yerine proje içindeki .venv/bin ya da venv/bin yolunu tercih eder: $PATH’teki bir python farklı bir ortamdır ve yanlış olandan bağlanmak, bozuk kod olarak okunan bir hatayla başarısız olur.

---

eval — kalıcı yorumlayıcılar

Değişkenleri, içe aktarmaları ve yüklenen verileri çağrılar arasında yaşamaya devam eden bir Python veya JavaScript hücresi. exec kademesi; paralel çalışmaya uygun değil.

Argüman	Anlamı
code	Hücre
description	Gerekli. Transkript etiketi için 5–10 sözcük
language	python (varsayılan) veya javascript
reset	Yorumlayıcıyı atar ve önce temiz bir tane başlatır

• Son ifade, bir notebook’un yaptığı gibi yankılanır.
• display() çalışır, bir pandas frame’i tablo olarak işlenir ve bir matplotlib şekli, transkriptin gösterdiği bir görüntü olarak geri döner.
• İnsanların refleks olarak yazdığı IPython deyimleri — %pip, %cd, !cmd, %%bash, %%timeit — düz koda dönüştürülür. %pip ayrıca sys.modules’u boşaltır; böylece sonraki import, az önce kurulmuş olanı görür.

Kendi araçlarınızı bir hücrenin içinden çağırma

contents = tool("read", {"path": "lib/auth.dart"})

Köprü, harness araç kayıt defterine yeniden girer; böylece korumalar, onay ve her sarmalayıcı, modelin yaptığı bir çağrıda olduğu gibi birebir uygulanır. Geri döngü soketi yerine kernel’in kendi borusunu kullanır: port yok, secret yok, dışa çıkış kuralı yok.

Hücrenin zaman aşımı bir hareketsizlik bütçesidir (varsayılan 5 dakika) ve köprü üzerinden gelen bir çağrı sonuçlanana kadar askıya alınır; böylece alt ajanlara dağılan bir hücre, dağıtımın ortasında öldürülmez.

Kernel nerede çalışır

Konuşmanın bir enclosure’ı varsa orada, yoksa ana makinede. Bunun için bir enclosure başlatmaz — bir rig sekmesinin kendiliğinden başlamasını engelleyen kuralın aynısı.

---

ask_user — insana soru sorma

read kademesi. Bir çalıştırmanın operatöre bir şey sormasının tek yolu. Konuşmada numaralandırılmış bir kart işler ve birisi yanıtlayana, atlayana ya da soru zaman aşımına uğrayana kadar bekler. Soruyu asla bir sohbet iletisi olarak yazmayın — bu, turu bitirir.

Argüman	Anlamı
question	Sorulacak şey
context	İsteğe bağlı: neden sorduğunuz ve yanıta neyin bağlı olduğu
options[]	Seçenekler, her biri {label, description?}
allow_free_text	Yazılı bir yanıtın kabul edilip edilmeyeceği
multi_select	Birkaç seçeneğin seçilip seçilemeyeceği

Atlamak başarıdır: belirtilen bir varsayımla ilerleyin ve tekrar sormayın. Zaman aşımı, aynı talimatı taşıyan bir hatadır. İzin istemleri (“bunu yapabilir miyim?”) ayrı bir kapıdır ve konuşmada aynı kart olarak işlenir.

Yalnızca hem bir soru portu hem de bir hedef alan var olduğunda kaydedilir. Bağlı bir insan yokken çağrı, sonsuza kadar bloke olmak yerine başarısız olur — bağlı bir onaylayıcı yokken bir koruma prompt’unun takındığı varsayılanı ret duruşunun aynısı.

---

vibe_* — arka plan worker’larını yönlendirme

Yalnızca vibe modu açıkken kaydedilir. Beşi de read kademesindedir: kapı, düzenlemenin gerçekte yapıldığı yer olan worker’ın kendi araçlarında olmalıdır.

Araç	Argümanlar	Notlar
vibe_spawn	brief, label, tier?	Hemen döner; worker çalışmaya devam eder
vibe_send	worker_id, message	Brifinge ekler ve yeniden çalıştırır
vibe_wait	worker_id, timeout_seconds?	Sonuçlanana kadar bekler
vibe_kill	worker_id	Onu durdurur
vibe_list	—	Kademe, durum, geçen süre ve son sonuç

tier, fast (net bir tanımlamaya sahip mekanik iş) ya da good (tasarım, muhakeme veya bir fast worker’ın ürettiklerini inceleme) olur.