Dokümantasyon / Geliştirici modu
Kod analizi
ivralo kodu üç yoldan okur: projenizin tanımladığı dil sunucuları, bu sunucuların ve git'in söylediklerini cache'leyen bir kod indeksi ve küçük bir context penceresini doldurmadan cevap veren okuma araçları. Bir sunucuyu tanımlamak, araçlar, indeks, sembol üzerinden düzenleme ve keşif bütçesi bu sayfada.
Dil sunucusu tanımlamak
Dil sunucusu, bir çağrının hangi login'e gittiğini, o sembolün gerçek kullanımlarının hepsini, tipini ve type checker'ın bir dosya hakkında ne dediğini bilir. ivralo hazır bir sunucu listesiyle gelmez ve kendi başına hiçbir şey başlatmaz. Yalnızca projenizin IVRALO.md'de, her dosya uzantısı grubu için bir satırla tanımladığı sunuculara sorar.
# Language servers
- py: pyright-langserver --stdio
- ts=typescript,tsx=typescriptreact,js=javascript: typescript-language-server --stdio
Uzantıları noktalı ya da noktasız yazabilirsiniz. suffix=id, sunucuya dosyanın dili olarak bildirilecek dil kimliğini belirtir. Bu verilmezse uzantının kendisi gönderilir. Daha uzun bir uzantı (d.ts) daha kısa olana göre önceliklidir. İki satırda birden geçen bir uzantı ilk satırda kalır. Sunucuyu PATH'inizdeki bir programın adıyla ya da repo içindeki bir yolla belirtin.
Güvenmek, onay vermek demektir. Bir sunucuyu başlatmak bir program çalıştırmaktır ve clone'ladığınız bir repo kendi IVRALO.md'siyle gelir. Bu yüzden siz klasöre güvenene kadar repo'nun tanımladığı hiçbir şey başlamaz. Güvendikten sonra bir .py dosyası hakkındaki ilk soru, py satırındaki sunucuyu ikinci kez sormadan başlatır. Oturumda, ivralo ask'te, zamanlanmış görevlerde ve ivralo index --code'da da durum aynıdır. Shell politikası komutu yine önce değerlendirir ve bir deny kaydı onu reddeder. Bir klasöre güvenmeden önce # Language servers satırlarını okuyun, çünkü bunlar çalışacak.
Sunucu ivralo'nun kendi süreç ağacında, repo içinde ve shell'in ortamıyla çalışır, ivralo kapanınca o da kapanır. Çöken bir sunucu bir kez yeniden başlatılır. İkinci kez çökerse araçlar oturumun geri kalanında bunu belirtir.
| Ayar | Varsayılan | Etkisi |
|---|---|---|
IVRALO_LSP_TIMEOUT | 30 | Sunucuya yapılan tek bir isteğin sürebileceği saniye |
IVRALO_LSP_WARMUP_WAIT | 15 | Hâlâ indeksleme yapan bir sunucu için beklenecek saniye |
ivralo doctor'da bir language servers bölümü vardır. Burada her satır için komutun PATH'te olup olmadığı ve politikanızın onu başlatmak hakkında ne dediği yazar. Başlatılabilecek sunucular için sürümü, hangi sorulara cevap verebildiği ve ısınmasının ne kadar sürdüğü de gösterilir.
Dil sunucusu araçları
| Araç | Neyi cevaplar |
|---|---|
goto_definition | Bir konumdaki sembolün nerede tanımlandığını |
find_references | Sembolün bütün kullanımlarını, önce sayısını vererek; within= aramayı daraltır, limit (en fazla 200) sonuç sayısını artırır |
find_implementations | Bir interface'i ya da abstract metodu implement eden sınıfları veya fonksiyonları |
call_hierarchy | Bir fonksiyonu kimin çağırdığını ya da onun neleri çağırdığını, tek seviye |
hover_info | Sembolün tipini ya da imzasını, ardından dokümantasyonunu |
code_diagnostics | Sunucunun bir dosya için raporladığı hataları ve uyarıları, önce hatalar |
rename_symbol | Sunucunun bulduğu her yerde yeniden adlandırma; uygulanmadan önce gösterilen bir düzenleme |
organize_imports | Sunucunun kendi organize-imports işlemi; bir düzenleme |
Konum, bir satır ve o satırdaki ad (symbol="login") ya da 1'den başlayan bir sütun numarasıdır. Sunucunun cevaplayamadığı bir durum açıkça belirtilir, hiçbir zaman boş liste olarak dönmez: hiçbir satırın kapsamadığı bir uzantı, sunucunun desteklemediği bir soru ya da hâlâ ısınan bir sunucu.
Kod indeksi
Kod indeksi, dil sunucunuzun ve git'in repo hakkında söylediklerinin .ivralo/index/index.sqlite içindeki cache'idir. Kendisi hiçbir şeyi parse etmez. Tanımları (sınıflar, fonksiyonlar, metotlar, modül seviyesindeki adlar, sınıf alanları) saklar; fonksiyonların içindeki değişkenleri saklamaz.
| Araç | Neyi cevaplar |
|---|---|
symbol_search | Bir adın nerede tanımlandığını: önce tam eşleşmeler, sonra önekler, sonra adı içerenler; testlerden önce kaynak kod |
file_outline | Bir dosyadaki sembolleri satır aralıklarıyla; böylece ajan yalnızca ihtiyaç duyduğu satırları okur |
Her cevap, repo'nun ne kadarının ve hangi commit'te indekslendiğini belirterek başlar. Dosyası o zamandan beri değişmiş bir sonuç stale olarak işaretlenir. Her tur indeksi en fazla IVRALO_CODE_INDEX_BUDGET saniye boyunca günceller (varsayılan 2; 0 kapatır). Böylece büyük bir repo birkaç turda dolar ve hiçbir turu bekletmez. Bütün maliyeti tek seferde ödemek isterseniz:
ivralo index --code # her dosyayı şimdi oku
ivralo index --code --rebuild # baştan başla
ivralo index --code --semantic # semantic_code_search için kodu da embed et
İndeks yalnızca bir cache'tir: .ivralo/index/'i silerseniz tek kaybınız yeniden oluşturma süresi olur. ivralo doctor indeksin hangi commit'i yansıttığını ve HEAD'in ne kadar gerisinde olduğunu gösterir.
Okuma yüzeyi
Üçüncü bir araç grubu, ajanın bir repo'yu bütün dosyaları context'ine yüklemeden okumasını sağlar. Her biri indeks, dil sunucusu, git ya da bilgi indeksi üzerinde çalışan bir sorgudur, hiçbiri parser değildir. Her cevap önce sayıyı verir ve kaynağı eski ya da eksikse bunu belirtir.
| Araç | Neyi cevaplar |
|---|---|
repo_summary | IVRALO.md'de tanımlananları, uzantıya göre dosyaları, üst seviye klasör yapısını, en sık değişen dosyaları, README'nin ilk paragrafını |
repo_tree | Önce dosya sayılarıyla klasörleri, birkaç seviye derinliğe kadar |
related_files | Aynı commit'lerde değişen, dosyanın sembollerini kullanan ya da adı benzeyen dosyaları, her birinin nedeniyle |
related_tests | Bir sembole referans veren testleri, ardından dosyayla ilgili testleri |
inheritance_graph | Bir tipin üst ve alt tiplerini |
dead_code_candidates | Çalışma alanında hiçbir yerden referans verilmeyen sembolleri; yalnızca aday olarak, hiçbir şey silinmez |
code_slice | Tek bir sembolü paket hâlinde: kodu, sınıf satırı, kullandığı import'lar, çağırdığı fonksiyonların imzaları ve testi; IVRALO_SLICE_BUDGET token (2.000) sınırı içinde, dışarıda kalanlar başlıkta listelenir |
semantic_code_search | Kodu ne yaptığına göre ("token nerede doğrulanıyor"); dosya, satır ve sembol bilgisiyle |
semantic_code_search kodu her çağrıda biraz biraz embed eder. Hepsini birden embed etmek için ivralo index --code --semantic kullanın. Hosted bir embedding modeli kullanılıyorsa kod makineden çıkmasın diye çalışmayı reddeder. IVRALO_EMBED_CODE_HOSTED=1 bu reddi kaldırır.
Sembol üzerinden düzenleme
Bir dil sunucusu yapılandırılmışsa ajanlar kodu edit_file'a kopyalamak yerine, değiştirdikleri şeyin adını vererek değiştirebilir:
| Araç | Ne yapar |
|---|---|
replace_symbol(path, symbol, new_text, line=0) | Tek bir fonksiyonu, metodu, sınıfı ya da sabiti değiştirir |
insert_before_symbol, insert_after_symbol | Bir sembolün hemen önüne ya da arkasına satır ekler |
delete_symbol(path, symbol, line=0) | Bir sembolü, yalnızca başka hiçbir yer ona referans vermiyorsa siler |
add_import(path, statement) | Import bloğunun sonuna bir import'u, yalnızca bir kez ekler |
replace_range(path, start_line, end_line, new_text, expected_text) | Tam olarak beklenen metni içeren satırları değiştirir; hiçbir sunucunun kapsamadığı dosyalar için |
format_file(path), format_changed_files() | Projenizin kendi formatter'ını çalıştırır |
Sembol, file_outline'da göründüğü şekilde adlandırılır (login ya da Session.login). Aynı adı taşıyan birden fazla sembol varsa line hangisi olduğunu netleştirir. Her düzenleme için dosyanın önce okunmuş olması gerekir. Sembolün satırları o zamandan beri değiştiyse düzenleme PATCH_CONFLICT ile durur. Dosyanın geri kalanı byte'ı byte'ına aynı kalır.
Düzenleme uygulandıktan sonra sunucunun dosya için verdiği hatalar öncekilerle karşılaştırılır ve yeni bir hata varsa raporlanır. IVRALO_EDIT_REFUSES_ON_DIAGNOSTIC=1 ise bu durumda düzenlemeyi geri alır.
ivralo hiçbir zaman kendi formatter'ını kullanmaz. Siz kendi formatter'ınızı tanımlayın:
# Commands
- format-paths: `uv run ruff format {paths}`
format-paths dosyaları kendi {paths} yer tutucusundan alır. Yalnızca format tanımlıysa formatter bütün çalışma alanında çalışır. İkisi de tanımlı değilse hiçbir şey formatlanmaz.
Var olan bir dosyaya write_file uygulamak coder için reddedilir ve bunun yerine sembol düzenlemeleri önerilir. IVRALO_WHOLE_FILE_WRITES=1 buna izin verir. Bütün sembol düzenlemeleri diğer düzenlemeler gibi onay ister. Başında kimse yokken allow_tools'taki edit_file bunları da kapsar (Düzenleme ve onaylar).
Keşif bütçesi
Her okuma aracının ucuzdan pahalıya doğru bir keşif seviyesi vardır ve coding skill'i dosyaları bu sırayla okur:
| Seviye | Araçlar |
|---|---|
| 1 | repo_summary, repo_tree, glob_files |
| 2 | symbol_search, file_outline, grep_files, related_files, related_tests |
| 3 | code_slice, goto_definition, find_references, find_implementations, call_hierarchy, inheritance_graph, hover_info, semantic_code_search |
| 4 | read_workspace_file |
Bir turun keşfe harcadığı token sayılır ve context göstergesinin yanında (explored 3.1k tokens (level 2)), tur özetinde ve ivralo ask --format json çıktısında gösterilir. Varsayılan olarak bu yalnızca bir tavsiyedir. Bir bütçe belirlerseniz uygulanır:
IVRALO_EXPLORATION_BUDGET=20000 # tur başına, uzman başına token; 0 = yalnızca tavsiye
IVRALO_EXPLORATION_FILE_LINES=200 # asla reddedilmeyen en geniş okuma
Bütçe açıkken 200 satırdan uzun bir okuma, ajan o turda dosyanın outline'ını almadıkça reddedilir. Bütçe aşıldıktan sonra 3. seviyedeki çağrılar ve bu kadar geniş okumalar da reddedilir. Her ret mesajında daha ucuz olan çağrı önerilir. Ucuz seviyelerin cevap veremediği durumlarda bütçe devreden çıkar: tanımlı dil sunucusu yoksa, dosyada sembol yoksa ya da dosya git'in listesinde değilse.
Bütçe ne olursa olsun, tek bir çalışmada arada hiçbir şey yazılmadan aynı okuma iki kez istenirse yeniden çalıştırılmaz, "you already have this" cevabı döner.