Proje kaynakları

Proje kaynakları, agent'lara bu iş yığınının hangi kodu kullandığını ve nerede çalışacağını söyler. Kaynaklar projeye bağlı kalır, bu yüzden depo URL'lerini veya yerel yolları her işe tekrar tekrar yapıştırmaya gerek kalmaz.

Bugün iki kaynak türü destekleniyor:

Kaynaklar bir göreve nasıl dahil olur

Bir agent proje içindeki bir iş üzerinde çalıştığında, Multica proje adını, proje açıklamasını ve kaynak listesini görevin bağlamına ekler ve çalışma dizinine .multica/project/resources.json dosyasını yazar.

Çalışma alanına bağlı depo listesi her zaman görev bağlamına dahildir. Projeye bağlı depolar, buna ek olarak bu iş yığınının kullandığı kodu ve varsayılan ref'i belirtir.

Bir yerel dizin yalnızca bağlı olduğu daemon için geçerlidir. Bir görevi yürüten daemon'ın eşleşen bir yerel dizini varsa, agent doğrudan o dizinde çalışır; diğer bilgisayarlar projenin GitHub depolarını veya çalışma alanı depolarını kullanmaya devam eder.

Bir GitHub deposu ekleme

Projeyi açın ve Kaynaklar altında "Kaynak ekle"yi seçin. Çalışma alanına zaten bağlı bir depo seçin veya bir Git URL'si yapıştırın. Çalışma alanı depoları Ayarlar → Depolar'da yönetilir; GitHub bağlandıktan sonra aynı sayfa, App'in yetkilendirildiği depoları içe aktarmak için GitHub'dan seç seçeneğini sunar.

Depolar GitHub ile sınırlı değildir: runtime'ın erişebildiği herhangi bir Git URL'si bir depo kaynağı olarak çalışır. Kendi sunucunuzda barındırılan Multica, Ayarlar → Entegrasyonlar → Git barındırma altında kendi sunucunuzdaki Forgejo, Gitea veya GitLab'e de bağlanabilir; bkz. Kendi sunucunuzda Git barındırma.

Bir proje oluştururken, depoları doğrudan Depolar altında da seçebilirsiniz. Bir proje birden fazla GitHub deposunu bağlayabilir.

Bir kaynağın ref'i, sonraki checkout'ların varsayılan olarak kullanacağı dalı, etiketi veya commit'i belirler. default_branch_hint yalnızca agent'a varsayılan dal ipucu verir ve bir dal değişikliğini zorlamaz.

Bir yerel dizin ekleme

Yerel dizin ekleme arayüzü yalnızca Masaüstü'nde bulunur, çünkü tarayıcılar bilgisayarınızdaki klasörleri seçemez.

1. Masaüstü'nün yerel daemon'ının çevrimiçi olduğundan emin olun.
2. Projenin Kaynaklar'ını açın veya proje oluşturma iletişim kutusunun Yerel dizin sekmesini kullanın — proje henüz yokken de aynı seçim yapılabilir.
3. "Yerel dizin ekle"yi seçin, ardından kullanılacak klasörü seçin.
4. Görevlerin bunu nasıl kullanacağını seçin — Doğrudan veya Paralel, "Görevler dizini nasıl paylaşır" bölümünde açıklanmıştır. Klasör, o makinedeki runtime'ın izole edebileceği bir git deposuysa Masaüstü Paralel'i, aksi halde Doğrudan'ı ön seçili getirir. Bunu orada değiştirebilir veya daha sonra Kaynaklar'dan dizinin yanındaki kalemle değiştirebilirsiniz.

Ön seçim yalnızca şu anda bağladığınız dizin için geçerlidir. Daha önce bağlanmış bir dizin, kaydedildiği modu korur — mevcut bir kurulum sizin haberiniz olmadan asla değiştirilmez.

Dizin mutlak bir yol olmalı, zaten var olmalı ve geçerli daemon tarafından okunabilir ve yazılabilir olmalıdır. Şu yollar reddedilir: sistem kökleri ve sürücü kökleri (/, C:\), ev dizinlerinin kendisi ve ev dizinlerinin üst dizinleri (/Users, /home, /root gibi) ve /etc, /var, /tmp, /usr, /opt gibi sistem dizinleri. Seçilen yol bir sembolik bağlantıysa, önce gerçek yoluna çözümlenir ve aynı kurallara göre yeniden doğrulanır; sıralı kilit de gerçek yol üzerinde uygulanır.

Her proje, daemon başına en fazla bir yerel dizin bağlayabilir. Bir takımdaki farklı bilgisayarlar, aynı proje için kendi dizinlerini ayrı ayrı bağlayabilir.

Görevler dizini nasıl paylaşır

Bir yerel dizinin, kaynak başına execution_mode ile ayarlanan iki çalıştırma modu vardır. Masaüstü bunları Doğrudan ve Paralel olarak etiketler; API, CLI ve bu sayfanın geri kalanı tanımlayıcıları kullanır.

in_place (varsayılan) — "Doğrudan"

Agent doğrudan sizin dizininizde çalışır ve görevler birer birer yürütülür. İki görev aynı gerçek dizini kullandığında, sonra gelen görev waiting_local_directory durumuna girer ve önceki görev dizini serbest bıraktıktan sonra devam eder. Aynı dizine farklı sembolik bağlantılar üzerinden ulaşan iki yol da aynı şekilde sıralanır.

Bekleme dizini değiştirmez. Bekleyen bir görev iptal edilebilir; aksi halde dizin kullanılabilir olana kadar bekler.

worktree — "Paralel"

Her görev, deponuzun kendi git worktree'sini alır; bu worktree, runtime'ın kendi çalışma alanı dizini içinde oluşturulur. Aynı dizindeki görevler eşzamanlı çalışır — hiçbiri beklemez ve hiçbiri çalışma kopyanıza yazmaz.

Dizinin en az bir commit içeren bir git deposu olmasını gerektirir. Değilse, görevler sessizce sıralı çalıştırmaya dönmek yerine açık bir hatayla başarısız olur. O makinedeki runtime'ın da bu modu desteklemesi gerekir. Runtime bunu bağlandığında bildirir ve Multica bir sürüm numarasına değil bu bildirime göre kapı kontrolü yapar — bir geliştirme derlemesi, hiçbir uygulaması olmadan yeterince yeni görünen bir sürüm dizesi taşıyabilir. Bildirim iki kez kontrol edilir: o makinedeki runtime bu yeteneği bildirmediği sürece kaynağı kaydetme reddedilir ve o makinedeki uygulamayı güncellemeniz için bir ipucu verilir; ayrıca her görev, onu gerçekten üstlenen runtime'a karşı yeniden kontrol edilir — böylece kaynak kaydedildikten sonra sürümü düşürülen bir makinenin görevleri, sessizce yerinde çalıştırılmak yerine bir nedenle iptal edilir. worktree istemek izolasyon istemektir; çalışma kopyanızı düzenlemek bunun yerine asla bir yedek yol değildir.

Agent'ın gördüğü ve sizin geri aldığınız şeyler:

• Agent, HEAD'den değil, sizin gördüğünüz durumdan başlar. Commit'lenmemiş düzenlemeleriniz ve izlenmeyen dosyalarınız worktree'ye yeniden uygulanır, böylece agent artık elinizde olmayan bir kodu incelemez. Kendi çalışma kopyanız, index'iniz ve stash listeniz asla dokunulmaz kalır. Bu durum sadakatle yeniden oluşturulamıyorsa — yeniden uygulamanın kapsadığından (2000 dosya / 200 MiB) daha fazla izlenmeyen içerik olması dahil — görev, tanımayacağınız bir ağaçtan başlamak yerine başarısız olur. Genel çözüm, henüz yok sayılmayan derleme çıktısını gitignore'a eklemek veya temizlemektir.
• Sonuç, deponuzda bir daldır — görev başına değil, iş başına bir tane: agent/<agent>/<issue> (bir sohbet için agent/<agent>/chat-<session>). Görevin Görev ayrıntıları paneli dal adını gösterir (ve kopyalamanıza izin verir); git branch ile de bulabilirsiniz. git log / git diff ile inceleyin ve birleştirmeyi veya cherry-pick'i kendiniz yapın. Multica bunu sizin için asla birleştirmez. Yarıda başarısız olan bir görev bile dalını bildirir, çünkü agent'ın ürettiği her şey yine de commit'lenmiştir.
• Bir takip görevi, son görevin bıraktığı yerden devam eder. Aynı işe gelen bir sonraki yorum o dalı yeniden checkout eder, böylece agent, kendi değişiklikleri başka bir dalda mahsur kalmış şekilde HEAD'den başlamak yerine, az önce teslim ettiği işin üzerinde durur. Yalnızca son görevden bu yana kendi dizininizde değiştirdikleriniz üzerine yeniden uygulanır — dal, geri kalanını zaten taşır. Dalı birleştirdiğinizde bir sonraki görev yine sizin HEAD'inizden başlar. Aynı iş üzerinde iki görev çakışırsa, ikincisi ilkinin işinden agent/<agent>/<issue>-<task> üzerine dallanır, çünkü git bir dal için yalnızca bir worktree'ye izin verir.
• Değişiklikleriniz agent'ınkiyle çakışırsa, çakışmayı agent çözer. Agent'ın yeniden yazdığı satırların aynısını siz de yeniden yazarsanız, git hangi sürümün kazanacağına karar veremez; bu yüzden görev çakışan bir worktree üzerinde başlar ve her şeyden önce birleştirmeyi bitirmesi söylenir — o worktree'de git status birleştirilmemiş yolları listeler. Herhangi bir dosyayı birleştirilmemiş bırakan bir görev hiçbir şey teslim etmez: başarısız olur, worktree'yi korur ve bir sonraki görev aynı değişiklikleri yeniden sunar; böylece değişikliğiniz asla sessizce kaybolmaz.
• Yalnızca Multica'nın sahip olduğu dallar devam ettirilir. Bir dalın devam ettirilip ettirilmeyeceği adına göre değil, bir sahiplik kaydına göre belirlenir: kayıt hangi konuşmaya ait olduğunu ve dalın hangi commit'te bırakıldığını taşır. Kendi oluşturduğunuz ve tesadüfen agent/<agent>/<issue> adını taşıyan bir dal asla checkout edilmez, üzerine eklenmez veya önceki bir görev olarak okunmaz — kayıtlı commit'i artık içermeyen bir dal da aynı şekilde davranılır; bu yüzden Multica'nın dalını silip aynı adla kendi dalınızı oluşturmak veya onu başka bir geçmişe force-move etmek güvenlidir. Bu durumlarda görev bunun yerine agent/<agent>/<issue>-<id> dalını kullanır. Teslim edilmiş bir dalın üzerine commit yapmak normal bir durumdur ve devam ettirmeyi bozmaz — commit'iniz bir sonraki görevde orada olur. Her dal ayrıca kendi başlangıç (baseline) commit'iyle başlar; bu, ilk görevin başladığı ağacı işaretler — dalı daha sonra tanımlayan da bu commit'tir ve git diff <baseline>..<branch> tam olarak agent'ın işidir. Dalını kaydedemeyen bir görev — bitirmeden önce başarısız olduysa, kayıt yazılamadıysa veya değişikliklerinizi dala taşıyan commit'in ötesine worktree'sini sıfırladıysa — başarısızlık bildirir ve worktree'sini korur; sonraki görevler kendilerine ait olduğunu kanıtlayamadıkları bir dalı devam ettirmek yerine yeni bir dal başlatır.
• Hiçbir şey sessizce kaybolmaz. Agent'ın commit'lemeden bıraktığı her şey, worktree kaldırılmadan önce o dala commit'lenir — görev yarıda başarısız olsa bile. Commit'in kendisinin yapılamadığı nadir durumlarda — örneğin commit.gpgSign etkin ve runtime'ın erişebildiği bir imzalama anahtarı olmayan bir depo — worktree kaldırılmak yerine bilerek korunur, görev başarısız olarak bildirilir ve deponuzda git worktree list işi tutan dizini gösterir.
• Hiçbir şeyi değiştirmeyen bir görev geriye hiçbir şey bırakmaz. Dalı, git branch'te boş bir kayıt olarak kalmak yerine silinir — önceki görevlerin işini taşıyan işin dalı olması durumu hariç; bu her zaman kalır.

Worktree, runtime'ın çalışma alanı dizininde yaşadığından, normal temizlik takvimiyle geri alınır. Deponuzda iki şey kalıcı olur: dal ve refs/multica/local-state/ altında dal başına bir gizli ref; bu ref sahibini ve dizininizin en son devam ettirildiğinde nasıl göründüğünü kaydeder. Gizli ref'ler git branch'te asla görünmez; git for-each-ref refs/multica ile listeleyebilirsiniz. Multica her birini dalıyla birlikte siler ve kendi sildiğiniz bir dala ait olanları, o depoda bir sonraki görev başladığında kaldırır — ya da hepsini birden git for-each-ref --format='%(refname)' refs/multica | xargs -n1 git update-ref -d ile kaldırabilirsiniz.

Bir görev sırasında ne yazılır

Agent'ın yaptığı kod değişikliklerinin ötesinde, runtime dizine, o anki yapay zekâ kodlama aracının ihtiyaç duyduğu talimat dosyalarını ve .multica/project/resources.json'ı da yazabilir. Bunları sürüm kontrolünde istemiyorsanız .gitignore'unuza ekleyin.

Multica, görev ortamlarını temizlerken bağlı bir yerel dizini asla silmez. Agent'ın dizinde yaptığı değişiklikler, bir yapay zekâ kodlama aracını terminalinizde kendiniz çalıştırdığınızdaki değişikliklerle aynı türdendir ve aynı incelemeyi gerektirir.

Kaynakları CLI ile yönetme

# Bir proje oluştururken bir depo bağlayın
multica project create \
  --title "Agent UX" \
  --repo https://github.com/multica-ai/multica

# Kaynakları listeleyin ve ekleyin
multica project resource list <project-id>
multica project resource add <project-id> \
  --type github_repo \
  --url https://github.com/multica-ai/multica \
  --ref main

# Belirli bir daemon'daki bir yerel dizini bağlayın
multica project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id>

# Bir yerel git deposunu bağlayın ve görevlerin kendi worktree'lerinde eşzamanlı çalışmasını sağlayın
multica project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id> \
  --execution-mode worktree

# Mevcut bir yerel dizini modlar arasında değiştirin
multica project resource update <project-id> <resource-id> --execution-mode worktree
multica project resource update <project-id> <resource-id> --execution-mode in_place

# Bir kaynağı kaldırın
multica project resource remove <project-id> <resource-id>

Kaynak değişiklikleri, bundan sonra oluşturulan görevleri etkiler; zaten sona ermiş görevlerin kayıtlarını yeniden yazmaz.

Sonraki adımlar

• Projeler — proje bağlamı, ilerleme ve lider hakkında bilgi edinin.
• Daemon ve runtime'lar — bir görevi hangi bilgisayarın üstlendiğini öğrenin.
• Görevler — waiting_local_directory gibi görev durumlarını görün.