Plan modu

Plan moduna geçmek

Plan modu kapalıyken de ivralo birkaç adımlı görünen istekler için plan yapar. Bunlar, çıktı uzantısıyla anılan iki ya da daha fazla dosya içeren (revenue.png and report.pdf) ya da birbirinden ayrı iki ya da daha fazla sıralama kelimesi geçen ("önce ... sonra") isteklerdir. Transcript'te bunun nedeni tek satırla yazılır. Kodlama istekleri ise zaten çoğunlukla tek adımlık bir plana dönüşür.

Taslak

Planlayıcı işe, düz Python ile hazırlanan bir çalışma alanı özetiyle başlar: her dosyanın boyutu ve türü, her CSV'nin ve çalışma kitabının sütunları, her PDF'in sayfa sayısı. Repo'larda özetin ilk satırında ağaç ve IVRALO.md'de tanımlı komutlar yer alır:

a git repository - 137 files, mostly .py (120), .md (14), .toml (3);
commands from IVRALO.md: test `uv run pytest`, lint `uv run ruff check .`

Planlama turunda hiçbir araç çağrılmaz. Ana ajan normalde okuma ve düzenleme yapabilir, ama plan yaparken denediği her çağrı reddedilir. Size soru soracak çağrılar da siz görmeden geri çevrilir. Yani plan taslağı hazırlamak hiçbir şeyi değiştirmez.

Plan dosyası

Her taslak çalışma alanında .ivralo/plans/<stamp>-<slug>.md dosyasına yazılır. Onay ekranı bu dosyayı gösterir ve adını belirtir. Dosyada kısa bir yaklaşım, numaralı adımlar, planlayıcının açık soruları ve bir doğrulama bölümü bulunur. Her adımda onu çalıştıracak uzman, birkaç kelimelik bir başlık, kendi başına anlaşılır bir görev tanımı ve adımın sonunda ortada olması gereken dosyalar yazar.

Dosyayı herhangi bir editörde açıp bir görevi yeniden yazabilir ya da bir adımı silebilirsiniz. Sonra e'ye basın: çalışacak olan, düzenlediğiniz dosyadır.

Dalgalar ve bağımlılıklar

Aksi belirtilmedikçe her adım kendinden önceki adımın üzerine kurulur. Bir adım, dosyalarını ya da cevabını kullandığı önceki adımları needs olarak belirtebilir ya da hiçbir adıma ihtiyaç duymayabilir. Plan dosyası bunu adımın satırının sonunda gösterir:

1. **Librarian** - Research the market
2. **Data Analyst** - Read the sales schema *(after nothing)*
3. **Report Writer** - Write the report *(after 1, 2)*

Planı bir model değil, ivralo dalgalar hâlinde çalıştırır: ihtiyaç duyduğu adımlar bitmiş her adım hemen, kendi turu olarak başlar. Yukarıdaki örnekte 1. ve 2. adım birlikte çalışır, 3. adım ikisinin bitmesini bekler. Bir adım yalnızca kendinden önceki adımlara bağlı olabilir. İleriyi ya da var olmayan bir adımı gösteren bir işaret raporlanır ve adım yine kendinden önceki adımın üzerine kurulur.

Birlikte çalışacak iki adım aynı dosyayı üretmeyi vaat etmemelidir. Onay ekranı bu çakışmayı çalıştırmadan önce gösterir. Yine de çalıştırırsanız bu iki adım hiçbir zaman aynı dalgaya düşmez. Aynı uzmanın bir dalgadaki adımları yine sırayla çalışır, çünkü her uzmanın tek bir Python worker'ı vardır. Bir dalgadaki birden fazla kodlama adımı ise, her biri kendi Code Engineer'ıyla, aynı anda çalışır (Paralel coder'lar ve worktree'ler).

Plan çalışırken giriş çubuğunun üstünde plan panosu görünür: adım sayısı, başlığı ve durumuyla her adım ve çalışan bir adımın altında o an ne yaptığı. Altıdan fazla adım varsa yalnızca ilerleyenler gösterilir; Ctrl+L bütün adımları gösterir. Bir adım çalışırken yazdığınız mesaj, uzmana bir sonraki araç çağrısında ulaşır ve sonraki bütün adımlara not olarak verilir.

Bir adım nasıl değerlendirilir

ivralo her dalgadan önce bir checkpoint alır: çalışma alanının, geçmiş üzerinden geri dönülebilecek bir kaydı. Adım çalıştıktan sonra vaat ettiği her dosya bu checkpoint'e göre değerlendirilir:

Adını yalnızca onu üreten aracın bilebileceği dosyalar (örneğin bir migration) alembic/versions/*.py gibi bir glob olarak vaat edilir. Eşleşen bir dosya oluşturulduğunda ya da değiştirildiğinde teslim edilmiş sayılır. İçinde < ya da > bulunan bir vaat yer tutucudur ve kontrol edilmez. Turu başarısız olmuş ya da reddedilmiş bir araç çağrısıyla biten ve bu durumu kimsenin düzeltmediği bir adım da başarısız sayılır. Bir adımın oluşturduğu Markdown ya da Word dosyasının sonuna, ivralo'nun adımın okuduklarından derlediği bir Sources bölümü eklenir.

Bir adım başarısız olunca

Başarısız bir adım hata ekranını açar. Ekranda vaat edilen her dosya, değerlendirme sonucuyla birlikte gösterilir, örneğin report.pdf (stale).

Düzeltilmiş adım, başarısız adımın arkasına (revised) işaretiyle eklenir. Başarısız adım da nedeniyle birlikte plan dosyasında kalır. Geri alma işlemi, dalganın üzerine yazdığı bütün dosyaları geçmişten geri getirir. Dalganın oluşturduğu dosyalar listelenir ve ancak ikinci kez onay verirseniz silinir. Bir adımın başarısız olduğu dalgada zaten çalışan adımlar tamamlanır, yeni adım başlamaz ve sonuncusu bitince plan durur.

Komut satırından

ivralo plan "rapor sayfasına bir CSV dışa aktarımı ekle ve belgele"
ivralo plan "..." --json        # bir script için yaklaşım, adımlar ve sorular
ivralo ask --plan "..."         # planı göster, run / revise / no diye sor, sonra çalıştır
ivralo ask --plan --yes "..."   # bir pipe içinde: sormadan çalıştır

ivralo plan plan dosyasını yazar ve ekrana basar. Bir pipe içinde çalışan ivralo ask --plan, --yes verilmezse planı çalıştırmaz. Orada başarısız olan bir adım, hiçbir şeye dokunmadan geri almanın nelere dokunacağını yazdırır.

Job olarak çalışan planlar

Job, kaydı PostgreSQL'de tutulan bir çalıştırmadır. Bu yüzden onu başlatan terminal kapansa da yaşamaya devam eder: ivralo resume <id> ile devam ettirilir. Onay gerektiren bir çağrı gelirse job, biri cevap verene kadar bekletilir (Job'lar).